Bibleref Specification

Audience

This document is intended for developers of computer systems that process content containing bibleref markup. See the bibleref overview for a introductory description of how content producers can use bibleref.

Status

This 12 June 2007 recommendation is a draft, and while implementations are encouraged to use it, some details may change in future versions. Your comments are welcomed, and should be emailed to bibleref@semanticBABBLE.com (replacing BABBLE with bible in the address).

Terminology

Within this document, the terms 'MUST', 'SHOULD', and 'MAY' (when capitalized) are used in the following specific senses:

MUST

this item is an absolute requirement

SHOULD

there may exist valid reasons not to treat this item as a requirement, but the full implications should be understood and the case carefully weighed before discarding this item

MAY

an item deserves attention, but further study is needed to determine whether the item should be treated as a requirement.

Principles

Bibleref adheres to the general principles of microformats, including:

• Solve a specific problem
• Start as simple as possible
• Design for humans first, machines second

In this spirit, bibleref attempts to add as few requirements as possible to achieve two goals:

1. unambigiously distinguishing Bible references from other text
2. ensuring the intended references are clearly specified

The first goal is accomplished by use of the bibleref class attribute. The second goal is accomplished by specifying the Bible reference in the title attribute when it would otherwise be unclear or incomplete.

Bibleref markup MUST specify bibleref as one of the class names for elements that contain Bible references: only elements that reference the bibleref class constitute bibleref markup.

Since (X)HTML allows class attributes on virtually any element, virtually any element can be designated a Bible reference through use of the bibleref class attribute. However, as a best practice, users SHOULD limit the text enclosed by a bibleref attribute to a Bible reference, to make it possible for parsers to determine the intended reference.

Unless other elements such as a or span are used, bibleref markup SHOULD use the cite element to indicate that a Bible reference is being cited. Regardless of which element is used, the presence of the bibleref class attribute is what designates an element as a Bible reference.

Using Bibleref with Other Elements

When bibleref markup is combined with other elements (for example, a span element for styling), the bibleref element MAY be placed outside and enclosing the other element to allow use of the inner title attribute for display purposes, e.g.

<cite class="bibleref" title="2Tim 2.15">
  <span title="Do your best to present yourself ...">2 Tim 2:15</span>
</cite>

It may be helpful in such cases to disable the tooltip by including style="display: none;" in the outer element.

Any content can be enclosed within the <cite> or <a> element that is designated as a bibleref by use of the bibleref class attribute. However, if the content cannot be unambiguously recognized and parsed (for example, a context-dependent phrase like "verse three of this chapter"), the content provider MUST use the title attribute to specify at least the book name, and optionally the chapter number, verse number, and Bible version, according to the following pattern:

[Version<sep>]Book<sep>Chapter<sep>Verse[-[Chapter<sep>]Verse]

Version

an alphabetic string designating a particular version or translation of the Bible. This element is optional. See Book Names for possible values.

Book

an alphabetic string designating one of the canonical or deutero-canonical books of the Bible. No spaces are allowed in the Book designator: "2Timothy" is valid, but "2 Tim" is not. See Book Names for possible values.

Chapter

an integer specifying a chapter reference. Processors MAY determine whether the Chapter number is valid for the given book (e.g. only the values 1-16 are valid for Mark's Gospel).

Verse

an integer specifying a verse reference. Processors MAY determine whether the Verse number is valid for the given book and chapter.

sep

a single character separating elements. Processors MUST allow any combination of spaces, periods, and colons, e.g. "2Tim 2:15", "2Tim.2.15", "2Tim 2 15".

The title attribute format specification does not allow discontinuous spans of verses as a single reference. For example, a reference like "2Tim 2:14-19, 3:16-17" should be marked as two references, as follows:

<cite class="bibleref">2Tim 2:14-19</cite>, <cite class="bibleref" title="2Tim 3:16-17">3:16-17</cite>

The title attribute is required for the second reference (which lacks a book name in the included text), but not for the first.

If the reference determined by processing the text of a bibleref element conflicts with the reference specified by the title attribute, the title reference is normative and MUST be produced by bibleref processors.

Here is a Perl regex for allowed formats in the title. $1 is the optional translation identifier. $2 is the book/chapter/verse reference, which is deliberately general to accommodate many different reference formats.

title="([\w\-]+[ :.])?\s*([^"]+)"

The specification allows flexibility in the format of processor output where it doesn't affect the semantics of the reference. A processor may therefore produce any of "2Tim 2.15", "2Tim.2.15", "2Tim 2:15", etc. Processors are not required to maintain the formatting of the original textual content or the title attribute.

Book Designators

Bibleref processors MUST recognize the book designators specified in Appendix C of the OSIS specification (the current version is 2.1.1: note this is a large PDF file).

Bibleref processors for English or other languages MAY recognize additional book identifiers, provided there is an unambiguous mapping to canonical book names.

Version Designators

English bibleref processors MUST recognize the version designators specified in Appendix C of the OSIS specification.