OSIS™ 2.0.1 User's Manual (draft)

Draft Version of OSIS User's Manual

Note the updated schema and users manual number. One of our users already spotted a bug and it has been corrected. Make sure the schema and users manual you are consulting correspond in the numbering.

As you go through this guide to the OSIS 2.0.1 schema, you are going to notice mistakes, omissions and examples you don't find useful. Those were not left as an exercise for the reader.

The editors discussed having a registry of Bible verses for people who contribute corrections, supply omissions or examples but feared that there might be more corrections, supplied omissions or examples than there are verses in the Bible. Not to mention that some verses are more popular than others.

So, as an alternative, future versions of the OSIS User's Manual will have a Contributor's section, which will list your name and the number of corrections or supplied omissions/examples that you have contributed to the manual. Counting by the editors will be final but generous and credit given for duplicates or suggestions not ultimately used in the form submitted. Please specify if you want your email contact information included as well. Address your comments, corrections, supplied omissions/examples, to osis-editors@bibletechnologieswg.org.

This manual is meant to be a guide for all users of the OSIS schema and your assistance will be appreciate both by the editors as well as the community of OSIS users.

1. Introduction to OSIS™

Welcome to the OSIS (Open Scriptural Information Standard™) User's Manual. OSIS is a set of XML structures that can be used to produce Bibles, commentaries, and related texts that can be easily interchanged with other users, formatted as HTML, PDF, Postscript or any other desired format, and searched on any personal computer. It provides a standard way to express such documents, which is important because it saves time, money, and effort for:

• authors, who will have less need to adjust their manuscripts for each different potential publisher;
• publishers, who will gradually come to experience lower costs by not having to manage converting texts presented by authors in so wide a variety of formats, and by not having to provide texts in a different form to each electronic-book system vendor out there (or pay indirectly for those vendors to do the conversions).
• and software vendors, who can avoid writing a lot of code to manage different formats, and thus make their programs smaller, faster, and more reliable.

The OSIS development team closely studied previous Bible encoding forms, as well as tools for literary encoding in general. By doing this we hope we have avoided some weaknesses, and gained from some strengths, of each one, and we thank the many people who worked on those prior specifications, as well as those who have provided help and feedback in developing OSIS itself, and testing it by encoding large numbers of Biblical and related texts. A list of participants may be found in an Appendix.

Users familiar with the Text Encoding Initiative will find OSIS markup quite familiar, because the bulk of the elements we define correspond directly to TEI elements, and almost always have the same name (though often simplified content). The schema also provides a TEIform attribute for such elements, so they can be recognized by form-aware processors as equivalent to their TEI counterparts. We have attempted to point out any elements below that do not have TEI equivalents, for the sake of anyone using both systems.

OSIS is provided as a free resource by the Bible Technologies Group™ (or BTG™), which is a collaborative effort of the American Bible Society, the Society of Biblical Literature, the Summer Institute of Linguistics, the United Bible Societies, other Bible Societies and related groups, and individual volunteers around the world. OSIS is designed to meet the needs of diverse user communities who read, study, research, translate or distribute biblical texts. This introduction gives a brief overview of OSIS before leading you step by step through producing your first OSIS text.

For more information on OSIS, you may wish to join the OSIS Users' Group. To do so, send mail to osis-user@whi.wts.edu, setting the Subject line to "subscribe". Online information about OSIS is also available at http://www.bibletechnologies.org and http://www.bibletechnologieswg.org.

2. Getting started

The first question that is often asked when learning that OSIS uses XML (a markup language) is: "I'm not a computer person. Can I learn to use OSIS?" If you can type and use even the most basic word processor or computer text-editing program, the answer is clearly "Yes!" OSIS was designed to be offer the beginning user a simple way to do the basic "markup" required for a standard biblical text. "Markup" refers to markers placed within the text, that indicate where useful units (or "elements") such as verses, quotations, cross-references, and other things begin and end.

If you know HTML, you already know most of what you need to know to use OSIS; OSIS uses the same pointy-bracket syntax as HTML (or XHTML to be completely precise). It merely provides a different set of element and attribute names. A few names such as "p" and "div" are the same; others are new, such as "verse". The core set of elements for OSIS is actually smaller than the set for HTML 3.2. To be sure, there are some complex cases that we deal with later, but you can do useful work with no more information than is provided in this basic manual.

The second question that is most often asked is: ‘Do I need an XML editor to do OSIS?’ This question often comes up after a friend of a friend has recommended some editor, and you then checked its price. XML editors vary from free to over $10,000.00 (US), and many are difficult to use (though XMetal™ is a notable exception, and not very expensive).

The basic answer is no, you do not need any special software. You can use any text editor you like to create OSIS documents (or any other XML documents, for that matter). Many will even color the tags for you, because they know how to color HTML tags and the languages are similar enough. However, you should have a way to check your documents for errors -- if your editor doesn't know enough about XML to warn you if you misspell a tag, or forget to end some element that you started, you will want to check for errors periodically using an "XML validator". Many such program are available for various computers; some are available as Web services. (See Appendix, Validating Your OSIS Document for pointers and instructions on web based validation services.) Both Internet Explorer and Netscape can also validate an OSIS file once you have installed the OSIS rules file (called a "schema") and an appropriate stylesheet.

An OSIS-aware text editor will do this checking for you, either on demand or continuously. A friendlier OSIS-aware text editor will provide help by showing you just which elements are permitted at any given place. The friendliest editors also give you the option to see and edit a fully-formatted view on demand, rather than staring directly at pointy-brackets. The choice between the many tools is a personal one, dictated by your working style, level of technical sophistication, goals, budget, and other factors.

3. Some authoring tools

The OSIS team is working even as this manual is being written to adapt free authoring tools that will hide most if not all of the markup from the casual user of OSIS. In the meantime, the best way to learn OSIS is to use a simple text editor, such as WordPad or Kedit on Windows, BBEdit or Alpha on MacOS, or vi or emacs on Linux. You can even use a word processor, though any formatting that you do in it won't matter (you would simply save the file as "text only").

The examples in this manual have been kept deliberately short and can be downloaded as a package from the OSIS website. After you have gained some basic skill using OSIS, you may want try out more sophisticated editors.

Editing is much easier with an editing program that is aware of XML rules in general, and OSIS in particular. For example, rather than seeing literal tags with pointy-brackets, you can have a choice of seeing that, or structural views of your document (say, as a tree or expandable outline), or fully-formatted views to facilitate print layout.

Many products are available that can help you edit XML documents. One style shows the literal XML source file, but colors tags, attributes, and other things to make them stand out. Most such programs also read an XML schema and ensure that you only insert elements and attributes are permitted by the OSIS schema (schemas, such as the OSIS one, declare what elements and attributes are permitted where in documents of a particular kind). One free and helpful tool of this kinds is jEdit, which runs on most platforms. It can be set up to know about many kinds of files, including XML files, and OSIS in particular.

With such an editor, you can see or print a basic a formatted view by using most any Web browser. Later in this manual are instructions for setting up an OSIS file with a style sheet (generally in CSS) so that typical browsers can deal with it.

There are also more word-processor-like XML editors, which primarily show a formatted view defined by some style sheet. These are mainly commercial. XML Spy is one such tool (see http://www.xmlspy.com/); XMetal (see http://www.corel.com/servlet/Satellite?pagename=Corel/Products/productInfo&id=1042152754863) is another.

For high-end layout and typesetting from XML source files, usually a stylesheet language called XSL-FO is used. Two of the more popular commercial XSL-FO solutions are 3b2 (see http://www.3b2.com/), and Antenna House (see http://www.antennahouse.com/). Non-XML-based composition systems such as Quark™ and TeX generally have ways to import XML, but using them for XML composition requires substantial expertise and effort.

4. Your First OSIS Document

Like HTML documents, an OSIS document starts with a header, and then goes on to the actual text content. The header identifies the file as being XML, and as using the OSIS schema. It also provides places to declare a bibliographical description of the work and of any other works cited; and a place to record a history of editing changes. Here is a short, but valid, OSIS document:

<?xml version="1.0" encoding="UTF-8"?>
<osis xmlns="http://www.bibletechnologies.net/2003/OSIS/namespace"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.bibletechnologies.net/2003/OSIS/namespace osisCore.2.0.1.xsd">
<osisText osisIDWork="thisWork" osisRefWork="bible" xml:lang="en-US">
<header>
<work osisWork="thisWork">
<title>Contemporary English Version</title>
<type type="OSIS">Bible</type>
<identifier type="OSIS">Bible.en.CEV.1995</identifier>
<rights type="x-copyright">Copyright 1995 American Bible Society</rights>
<scope>Esth.1.1-Esth.1.4</scope>
<refSystem>Bible</refSystem>
</work>
<work osisWork="bible">
<type type="OSIS">Bible</type>
<refSystem>Bible</refSystem>
</work>
</header>
<div type="section" scope="Esth.1.1-Esth.1.4">
<title>Queen Vashti Disobeys King Xerxes</title>
<p>
<verse sID="Esth.1.1-Esth.1.2" osisID="Esth.1.1 Esth.1.2" n="1-2"/>
King Xerxes of Persia lived in his capital city of Susa and ruled one
hundred twenty-seven provinces from India to Ethiopia.
<verse eID="Esth.1.1-Esth.1.2"/>
<verse sID="Esth.1.3" osisID="Esth.1.3"/>
During the third year of his rule, Xerxes gave a big dinner for all
his officials and officers. The governors and leaders of the provinces
were also invited, and even the commanders of the Persian and Median
armies came.
<verse eID="Esth.1.3"/>
<verse sID="Esth.1.4" osisID="Esth.1.4"/>
For one hundred eighty days he showed off his wealth and spent a lot
of money to impress his guests with the greatness of his kingdom.
<verse eID="Esth.1.4"/>
</p>
</div>
</osisText>
</osis>

5. XML and OSIS declarations

The first several lines of any OSIS document will generally be identical:

The first line above identifies the document as being XML; this is required in exactly the form shown, and enables computers to identify how to process the rest of the document.

The second through third lines are a very long start-tag for the outermost OSIS element, which is called "osis." All elements in an OSIS document must be declared within the OSIS namespace. There are two ways to achieve this and other than remembering to pick one of the two following methods, that is all you need remember about it to start encoding texts using OSIS 2.0.

OSIS Namespace, Method 1: Copy the following lines just after <?xml version="1.0" encoding="UTF-8"/>:

<osis xmlns="http://www.bibletechnologies.net/2003/OSIS/namespace"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.bibletechnologies.net/2003/OSIS/namespace osisCore.2.0.1.xsd">

OSIS Namespace, Method 2: Copy the following lines just after <?xml version="1.0" encoding="UTF-8"/>:

<osis:osis xmlns:osis="http://www.bibletechnologies.net/2003/OSIS/namespace"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.bibletechnologies.net/2003/OSIS/namespace osisCore.2.0.1.xsd">

At this point, the OSIS document has begun. This sample is a single document rather than a collection of documents, so the next element opened is osisText:

<osisText osisIDWork="CEV" osisRefWork="Bible" lang="en">

Every osisText needs to supply an osisIDWork attribute and value. The value will generally be the short name of what is being encoded, in this case the Contemporary English Version, or CEV. The short name is defined in the work declaration for the work, described later. The work element that identifies the work being encoded should be the first work element, if the text has more than one. This sets things up for some of the later elements nested within the osisText element. One such element is work. It requires an osisWork attribute. That attribute's value has to be the same as the value found on the osisIDWork attribute of osisText (see line 7 of the sample). Other elements use/require an osisID attribute which refer back to the osisIDWork attribute of osisText (see lines 19 and 21 of the sample).

Every osisText also needs to specify what reference or versification scheme any osisRefs within it refer to. This may or may not be the same work. Depending on how finely you distinguish things, there are several major versification traditions, and countless fine-grained variations. For the present, we identify and reserve names for these major traditional reference systems:

• NRSVA New Revised Standard Version with Apocrypha
• NA27 Nestle-Aland, 27th Edition of the Greek New Testament
• KJV King James Version or Authorized Version (AV)
• LXX Septuagint
• MT Masoretic Text. Hebrew tradition varies in several respects, the best known being that it numbers what is given as a title for Psalms in most English translations as verse 1,and the beginning of the psalm in such a translation as verse 2.
• SamPent the Samaritan Pentateuch used a quite different numbering system.
• Synodal Russian
• Vugl Vulgate
• Loeb This system is used for most classical literature, though many major works have other systems as well.

OSIS is developing a schema for declaring versification systems formally, and for declaring some systems in terms of others. This will enable programs to map between systems. However, at this time we merely reserve the names above for some systems we know to be substantially different and important.

6. Canonical vs. non-canonical parts of a work

The element osisText has one other important attribute that is not shown above. It is called "canonical", and always has a value of "true" or "false". When true, it asserts that the content is a part of the text being encoded. For example, the "text" of the Bible includes the content of books, chapters, and verses but does not include notes, section-headings added by editors or translators, etc.

The canonical attribute is available on all elements. Its value inherits in the same manner as xml:lang. Because of this inheritance, encoders will seldom need to make this attribute explicit. In osisText this attribute is set to a default value of "true", while header, note, and reference that setting is overidden by setting the value of that attribute to be "false."

In books other than the Bible, a similar distinction holds: the text proper of Herodotus' Histories must be contained in elements with canonical="true", while notes, header data, and the like must not.

The meaning of this attribute is limited. It must not be used to encode interpretive or theological judgements about canonicity. For example, encoders who include the apocryphal books of the Bible, or the alternate longer ending to the Gospel of Mark, must mark them as canonical (whether by default or explicitly). This is simply because they are part of the text being encoded. Users of a text are never justified in drawing conclusions about a translator's, editor's, or encoder's position on questions of inspiration or other theological questions based on how they set the canonical attribute, because the attribute does not mean that.

In most cases use of the canonical attribute is straightforward, and we expect that the default values will almost always produce the intended result. However, there will arise truly difficult cases: for example, one may be encoding an ancient text with annotations of its own. In that case those notes would be canonical, while any added by the current editor would not be. In such cases, the practice chosen and its rationale should be described in the work's documentation.

7. The OSIS text header

The first element within every osisText must be a header. The header declares various works (including the work being encoded and any that are being referenced), and provides a place to keep a revision history of the text.

yyyy-mm-ddThh:mm:ss

1999-12-25

<change><date>2003-09-11</date>
<p>sjd: Filling in the gaps. Adding some info for 2.0 as defined
at the Calvin College meetings.</p>
</change>
<change><date>2003-07-01</date>
<p>sjd: Annotated alpha list of elements. Reworked reference and
work sections and added type, scope, and explanations of type and
subtype for work. Explained more elements and attributes.</p>
</change>
<change><date>2003-06-17</date>
<p>sjd: Wrote conformance section. Added lists of elements and
attributes, USMARC list. Inserted placeholders for doc on all element
types. Got document back to XML WF. Wrote CSS stylesheet.</p>
</change>

<osisText osisIDWork="CEV" osisRefWork="Bible" lang="en">
<header>
<work osisWork="CEV">

<work osisWork="EG">
<title>Egyptian Grammar</title>
<creator role="aut">Alan Gardiner</creator>
<contributor role="dte">Francis Llewellyn Griffith</contributor>
<date event="original" type="gregorian">1927</date>
<date event="eversion" type="gregorian">2003</date>
<type type="x-grammar">Grammar</type>
<publisher>Griffith Institute, Ashmolean Museum, Oxford</publisher>
<language type="ISO-639">EN</language>
<language type="Ethnologue">EG-ancient</language>
<identifier type="ISBN">0900416351</identifier>
<identifier type="LCCN">95230980</identifer>
</work>

<work osisWork="CPV">
<title>Cotton Patch Version of Luke and Acts: Jesus' Doings and
the Happenings</title>
<creator role="aut">Clarence Jordan</creator>
<date event="original" type="gregorian">1969</date>
<date event="eversion" type="gregorian">2003</date>
<type type="x-bible">Bible</type>
<publisher>Association Press
<name type="place">New York, NY</name></publisher>
<language type="ISO-639">EN</language>
<identifier type="ISBN">0809617250</identifier>
<identifier type="LCCN">69-18840</identifer>
<scope osisRef="Luke" />
<scope osisRef="Acts" />
</work>

<identifier type="ISBN">0809617250</identifier>
<identifier type="LCCN">69-18840</identifer>

<subject type="ATLA">Fathers of the Church</subject>

yearly:06-04T~(Vespers)

8. Title Pages

In order to make the encoding of title pages as found in standard works easier, OSIS 2.0 introduced the titlePage element. This element contains the following elements from the header: title, contributor, creator, subject, date, description, publisher, type, format, identifier, source, language, relation, coverage, which are explained in the material on the header section. Three additional elements are allowed, which are figure, milestone, and, p. Due to the complexity of title pages, all of these elements may occur in any order inside the titlePage element.

The titlePage element can occur within the osis, osisText, and, osisCorpus elements.

Users just starting with OSIS should use a minimum headers and simple titlePage element until they have gained some experience with text encoding and determining what is, or perhaps more importantly, what is not useful to have encoded in a work.

9. Basic Elements

While book, chapter, and verse numbers are a familiar and useful way of referring to locations in the Bible, they often conflict with the boundaries of parables, stories, genealogies, paragraphs, quotations, and other important units of understanding. Even to print a well-formatted Bible edition, and much more to support high-end search, annotation, and other capabilities, these meaningful units must also commonly be marked.

It is possible to encode a Bible using only book, chapter, and verse markup. However, most encoders also want to also represent sections, paragraphs, quotations, and so on. Higher-level structures are tagged as div, for "division", with a type attribute to specify the particular significance. div elements can occur within other div elements to any number of levels. The first and outermost div should occur immediately after the end of the header. For example,

<div type="book" osisID="Gen">
<head>Genesis</head>
<chapter osisID="Gen.1">
<head>1</head>
<verse osisID="Gen.1.1">In the beginning,...</verse>
<verse osisID="Gen.1.2">The earth was formless and void...</verse>
...
</chapter>
</div>

The div element is used for many top-level components, and so makes heavy use of the type attribute. The pre-defined types include the most common major divisions found in present-day Bibles and related works:

The main body of a Bible will typically consist of div elements of type="bookGroup" (such as each Testament, the Apocrypha, and perhaps smaller groups such as the Pentateuch, the Minor Prophets, etc), plus any front and back matter divisions (the selection of which varies greatly between editions).

With each bookGroup div, there will typically be book divs corresponding to each included Canonical or deutero-canonical book. Some books are divided into majorSections (such as the sub-books in Psalms), sections (typically topical divisions with headings), subSections (occasional minor divisions within sections). A specific chapter element is provided and encouraged, though div type="chapter" is also permissible.

Below this point typical texts switch from successive levels of div elements, to more specific markup such as paragraphs, lists, quotations, inscriptions, and the like. Also at this level, the markup begins commonly to interact with verse markup.

Use of the types defined for div is mandatory when a provided type is applicable. For example, a colophon must be marked up as <div type='colophon'>. If types not provided are needed, they may be added but must begin with "x-", to distinguish them from OSIS-standard values.

Such markup forms the primary backbone of an OSIS document. Chapter and verse elements are important (particularly for retrieval), but considered to be an overlay onto the more linguistic or thematic structure. Therefore, so long as verses or chapters do not cross the boundaries of other elements, they may be expressed in the normal fashion (NASB):

<chapter osisID="Mark.10">
<head>Mark Chapter 10</head>
<div type="section"><head>Divorce</head>
<verse osisID="Mark.10.1">Jesus then left that place and went into
the region of Judea and across the Jordan. Again crowds of people
came to him, and as was his custom, he taught them.
</verse>
<verse osisID="Mark.10.2">Some Pharisees came and tested him by
asking, "Is it lawful for a man to divorce his wife?"
</verse>
<verse osisID="Mark.10.3">"What did Moses command you?" he replied.
</verse>
<verse osisID="Mark.10.4">They said, "Moses permitted a man to write
a certificate of divorce and send her away."
</verse>
<verse osisID="Mark.10.5">"It was because your hearts were hard that
Moses wrote you this law," Jesus replied. </verse>
<verse osisID="Mark.10.6">"But at the beginning of creation God 'made
them male and female.' </verse>
<verse osisID="Mark.10.7">'For this reason a man will leave his
father and mother and be united to his wife,</verse>
<verse osisID="Mark.10.8">and the two will become one flesh.' So they
are no longer two, but one. </verse>
<verse osisID="Mark.10.9">Therefore what God has joined together, let
man not separate."</verse>
<verse osisID="Mark.10.10">When they were in the house again, the
disciples asked Jesus about this. </verse>
<verse osisID="Mark.10.11">He answered, "Anyone who divorces his wife
and marries another woman commits adultery against her. </verse>
<verse osisID="Mark.10.12">And if she divorces her husband and
marries another man, she commits adultery." </verse>
</div>
...
</chapter>

10. Simple paragraphing, quotes, and notes

Paragraphs (element p), quotations (element q), and other grouping elements can be inserted around groups of verses, as shown below. Likewise, note elements can be inserted where needed. The paragraph need not give an osisID for the set of verses it contains, since they are typically provided on the verse elements themselves:

...
<p>
<verse osisID="Esth.4.10">Then Esther spoke to Hathach, and gave him
a command for Mordecai: </verse>
<verse osisID="Esth.4.11"><q>All the king's servants and the people
of the king's provinces know that any man or woman who goes into the
inner court to the king, who has not been called, he has but one law:
put all to death, except the one to whom the king holds out the
golden scepter, that he may live. Yet I myself have not been called
to go in to the king these thirty days.</q> </verse>
<verse osisID="Esth.4.12">So they told Mordecai Esther's words.
</verse> </p>
<p>
<verse osisID="Esth.4.13">And Mordecai told them to answer Esther:
"Do not think in your heart that you will escape in the king's palace
any more than all the other Jews. </verse>
</p>
<p>
<verse osisID="Esth.4.14">For if you remain completely silent at this
time, relief and deliverance will arise for the Jews from another
place, but you and your father's house will perish. Yet who knows
whether you have come to the kingdom for such a time as this?"
</verse>
</p>
<p>
<verse osisID="Esth.4.15">Then Esther told them to reply to Mordecai: </verse>
<q>
<verse osisID="Esth.4.16">"Go, gather all the Jews who are present in
Shushan, and fast for me; neither eat nor drink for three days, night
or day. My maids and I will fast likewise. And so I will go to the
king, which is against the law; and if I perish, I perish!
</verse></q>
</p>
<p><verse osisID="Esth.4.17">So Mordecai went his way and did
according to all that Esther commanded him.<note
type="textual">Septuagint adds a prayer of Mordecai
here.</note></verse> </p>

Notice in this example that all the paragraphs and quotations still enclose an exact number of verses; there are exceptions to this elsewhere in the Bible, that need special handling as explained later.

When tagging quotations, do not also include quotation marks. They will be generated in the typesetting or display process. This is important for several reasons. FIrst, if some people use q, some use punctuation marks, and some use both, anyone processing OSIS texts will have to check every text and account for all the variations -- this is expensive and time-consuming: that is, it will make the Bibles cost more (to someone), and be delivered later. Another reason is that punctuation for quotes differs around the world; so any given quotation mark may be meaningless to other communities. In Spanish, for example, there are special rules about how to mark quotes that continue after an interruption -- such cases can be distinguished by adding a type attribute to the q element, with values such as initial, medial, and final.

Many editions of the Bible have accompanying notes, often of several distinct types. A number of predefined types, and some additional internal structure, are discussed later. It is customary to include the notes directly within the text, at the point to which they apply. This can be done via the note element, which can be placed almost anywhere. In the future, it is likely that notes will more commonly reside outside of the text, instead residing in special notes-files that can be attached (via osisRef) to any Bible edition on request.

Every note should have a type attribute to indicate its purpose; many Bible editions show different kinds of notes in different places. The pre-defined note types are listed below; they are not sharply-defined, wholly distinct categories. In addition, if none of these categories suffice, encoders may create their own so long as their names begin with "x-".

• allusion The note explains an implicit reference the text makes to another text or concept.
• alternative The note records an alternate possible reading of the text, whether due to ambiguity in translation or to manuscript variation.
• background The note provides background information, such as cultural norms, explanations of geographic or other information original readers would have known, and so on.
• citation The note cites a supporting text or further explanation of some kind.
• crossReference The note provides a cross-reference to a related passage or other text.
• devotional The note includes information of interest for devotional reading.
• exegesis The note discusses a relevant point of exegesis or interpretation
• explanation The note explains implicit, ambiguous, or otherwise non-obvious aspects of the passage.
• speaker [2.0] This type is intended mainly for use in sermons and other performance texts, where the performer may wish to make notes to him or herself. For example, "tell joke here".
• study The note provides helps for a deeper study of the passage.
• translation The note discusses an issue of translation, such as a word whose meanining is unclear in the original, or a reasons for the translator's choice of phrasing. Bible translation projects will likely use this heavily, using the subtype attribute to mark the status of each note as resolved or unresolved, the person responsible for the note, and so on.
• variant The note records a textual variation in manuscript tradition, relevant at its location.

Sometimes a verse or chapter starts or end in the middle of some other unit, such as a poetic line group, paragraph, quotation, or speech. In such cases an alternate form of the verse or chapter tags must be used. This usage is explained in the next section.

11. Elements that cross other elements

The normal form of an element is a start tag and an end tag: <verse>...</verse>. For handling markup that crosses boundaries, however, a special form must be used. It consists of two totally empty instances of the same element type: one to mark the starting point, and one to mark the ending point. The two empty elements identify themselves as to which is the start and which is the end, and co-identify themselves by the sID attribute (the start of the traditional element) and the eID attribute (the end of the traditional element), the values of which must match.

Empty elements are indicated in XML by a tag with "/" preceding the final ">": thus "<verse/>" rather than <verse> or </verse>. Elements used in this way are commonly called "milestones", and those particular elements in OSIS that permit this alternate encoding are thus called "milestoneable". Elements that are "milestoneable" in the OSIS schema are:

• abbr
• chapter
• closer
• div
• foreign
• l
• lg
• q
• salute
• seg
• signed
• speech
• verse

This is particularly useful where modern translations break up verses or other traditional divisions in a Bible text. For example, a paragraph based encoding of part of the Book of Esther would appears as follows:

<p>
<verse sID="Esth.2.7" osisID="Esth.2.7"/>Mordecai had a very beautiful cousin named Esther, whose Hebrew name was Hadassah. He had raised her as his own daughter, after her father and mother died.<verse eID="Esth.2.7"/>
<verse sID="Esth.2.8" osisID="Esth.2.8"/>When the king ordered the search for beautiful women, many were taken to the king's palace in Susa, and Esther was one of them.</p>
<p>Hegai was put in charge of all the women,<verse eID="Esth.2.8"/>
<verse sID="Esth.2.9" osisID="Esth.2.9"/>and from the first day, Esther was his favorite. He began her beauty treatments at once. He also gave her plenty of food and seven special maids from the king's palace, and they had the best rooms.<verse eID="Esth.2.9"/>
</p>

There are two things to note about the Esther example:

• Esther 2:8 is divided by a paragraph (the p element and so must be marked using the verse element as a milestones with the sID and eID attributes to link those two milestones together.
• Where overlapping elements are necessary, the milestoneable element technique must be used for the entire text. That is, it is an error to mark some verses in Esther with traditional verse elements, i.e., as containers and others with the milestoneable verses. The reason is quite simple, inconsistent markup is more difficult to process and makes the encoded text less useful for everyone.

This is equivalent to the TEI "milestone" method for marking such phenomena. It has the advantage that milestones representing a given type of element have the same name as the element, and automatically have the same attributes. Although XML itself will not detect a validation error if attributes other than eID are specified on the ending milestone, eID is specified on the starting milestone, or the start and end milestones are in the wrong order, each of these conditions is an OSIS error.

For OSIS purposes, there is no semantic difference between marking up a chapter or verse as a container using a start and end tag, versus marking it up as a "milestone pair" consisting of two empty tags.

Note: Typesetting and layout systems vary in their ability to accommodate non-hierarchical markup such as this. Fortunately, in most Bible editions the only formatting consequence of a verse element is insertion of the verse number, and perhaps insertion of a line-break; these are within the capabilities of most layout and style systems even though the verse is not a container in XML terms.

12. Special Text Types

The bulk of the remaining OSIS elements fall into a few simple classes: First, markup for special text types, such as epistles and drama. Second, generic structures such as lists, tables and glossaries (typically found in appendixes of printed Bibles). And finally, small-scale elements that mark, quotations, notes, names, index entries, and the like.

<div type="book" osisID="1Tim">
<head>The First Epistle to Timothy</head>
<chapter osisID="1Tim.1">
<salute>
<verse osisID="1Tim.1.1">FROM: PAUL, a missionary of Jesus Christ,
sent out by the direct command of God our Savior and by Jesus Christ
our Lord -- our only hope.</verse>
<verse osisID="1Tim.1.2">To: Timothy. Timothy, you are like a son
to mein the things of the Lord. May God our Father and Jesus Christ
our Lord show you his kindness and mercy and give you great peace
of hear and mind.</verse>
</salute>
<verse osisID="1Tim.1.3">...</verse>
</chapter>
...
</div>

<castList>
<castGroup>
<head>Cast of characters</head>
<castItem>
<actor>Patrick Durusau</actor>
<role>Job</role>
<roleDesc>A man of God who suffers greatly</roleDesc>
</castItem>
<castItem>
<actor>(a whirlwind)</actor>
<role>God</role>
<roleDesc>The Almighty, who permits Job's suffering, and
responds to his questions about it.</roleDesc>
</castItem>
<castItem>
<actor>(a disembodied voice)</actor>
<role>Satan</role>
<roleDesc>The instigator of Job's suffering</roleDesc>
</castItem>
<castItem>
<actor>Todd Tillinghast</actor>
<role>Eliphaz</role>
<roleDesc>The first of Job's friends to speak</roleDesc>
</castItem>
<castItem>
<actor>Chris Little</actor>
<role>Bildad</role>
<roleDesc>The second of Job's friends to speak</roleDesc>
</castItem>
<castItem>
<actor>Steve DeRose</actor>
<role>Zophar</role>
<roleDesc>The third of Job's friends to speak</roleDesc>
</castItem>
<castItem>
<actor>Troy Griffiths</actor>
<role>Elihu</role>
<roleDesc>The youngest and last of Job's friends to speak,
who was slightly less clueless than the rest.</roleDesc>
</castItem>
</castGroup>
</castList>

<div osisID="NRSV.Song.2">
<speech>
<speaker>woman</speaker>
<verse osisID="NRSV.Song.2.1">I am a rose of Sharon, a lilly of the valleys.</verse>
</speech>
</div>

<div osisID="NRSV.Song.2">
<speech who="woman">
<verse osisID="NRSV.Song.2.1">I am a rose of Sharon, a lilly of the valleys.</verse>
</speech>
</div>

<chapter osisID="Acts.7">
<head>Stephen's Speech to the Sanhedrin</head>
<verse osisID="Acts.7.1" sID="a71"/>Then the high priest asked him, <speech>Are
these charges true?</speech>
<verse eID="a71">
<verse osisID="Acts.7.2" sID="a72"/>To this he replied:
<speech>Brothers and fathers, listen to me! The God of glory appeared
to our father Abraham while he was still in Mesopotamia, before he
lived in Haran. <verse eID='a72'/>
<verse osisID="Acts.7.3" sID="a73">'Leave your country and your people,' God
said, 'and go to the land I will show you.'<verse eID="a73"/>
<verse osisID="Acts.7.4" sID="a74"/>"So he left the land of the Chaldeans and
settled in Haran. After the death of his father, God sent him to this
land where you are now living. <verse eID="a74"/>
<verse osisID="Acts.7.5" sID="a75"/>He gave him no inheritance here, not even a
foot of ground. But God promised him that he and his descendants
after him would possess the land, even though at that time Abraham
had no child. <verse eID="a75"/>
<verse osisID="Acts.7.6" sID="a76"/>God spoke to him in this way: 'Your
descendants will be strangers in a country not their own, and they
will be enslaved and mistreated four hundred years. <verse eID="a76"/>
<verse osisID="Acts.7.7" sID="a77"/>But I will punish the nation they serve as
slaves,' God said, 'and afterward they will come out of that country
and worship me in this place.'<verse eID="a77"/>
<verse osisID="Acts.7.8" sID="a78"/>Then he gave Abraham the covenant of
circumcision. And Abraham became the father of Isaac and circumcised
him eight days after his birth. Later Isaac became the father of
Jacob, and Jacob became the father of the twelve
patriarchs.<verse eID="a78"/>
...
<verse osisID="Acts.7.53" sID="a79"/>you who have received the law that was put
into effect through angels but have not obeyed it.
<verse eID="a79"/>
</speech>
...</chapter>

<div type='section' scope='Ps.7.1-Ps.7.17'>
<title>The <divineName type='x-yhwh'>LORD</divineName> Always Does Right</title>
<lg>
<l>
<verse sID='Ps.7.1' osisID='Ps.7.1'/>You, <divineName type='x-yhwh'>LORD</divineName> God,<lb type='x-secondLine'/>are my protector.</l>
<l>Rescue me and keep me safe<lb type='x-secondLine'/>from all who chase me.<verse eID='Ps.7.1'/>
</l>
<l>
<verse sID='Ps.7.2' osisID='Ps.7.2'/>Or else they will rip me apart</l>
<l>like lions<lb type='x-secondLine'/>attacking a victim,<lb type='x-secondLine'/>and no one will save me.<verse eID='Ps.7.2'/>
</l>
</lg>
</div>

<figure src="Beckmann_1917.jpg" alt="Painting by Max Beckmann, titled
Christ and the Woman taken in Adultery"><caption>Christ and
the Woman Taken in Adultery by Max Beckmann,
1917</caption><index index="illustrations"
index1="Beckmann, Max">
</figure>

<milestone type="pb" n="37-verso"/>
<p>The Lord said to Eliphaz:<milestone type="line"/>
What my servant Job has said about me is true, <milestone type="line"/>
but I am angry with you and your two friends for <milestone type="line"/>
not telling the truth. <verse osisID="Job.42.8">So I want you to go
over to <milestone type="line"/>
Job and offer seven bulls and seven goats on an <milestone type="line"/>
alter as a sacrifice to please me. After this, Job <milestone type="line"/>
will pray, and I will agree not to punush you for <milestone
type="line"/>your foolishness.</verse><milestone type="line"/>
<verse osisID="Job.42.9">Eliphaz, Bildad, and Zophar obeyed the Lord,
and he answered Job's prayer.</verse>

13. Common elements in all texts

The elements found in this section can be found in almost any encoded text.

<p>See Edwards' famous treatise on <a
href="http://www.ccel.org/e/edwards/affections/religious_affections.html">religious
affections</a> for additional information.</p>

<head>On Justice<index name="topic" level1="Virtues"
level2="Justice"/>

<index name="topic" level1="Virtues" level2="Justice" see="Fairness"/>

<abbr expansion="Journal of Biblical Literature">JBL</abbr>

<verse osisID="NRSV:Ezek.19.5">When she saw that she was thwarted,
that her hope was lost, she took another of her cubs and made him a
young lion.</verse> <note>It is uncertain to which king <catchWord
osisRef="Ezek.19.5">another of her cubs</catchWord> refers....</note>