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 4 July 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).

The permanent link for this version of the specification is http://semanticbible.com/bibleref/bibleref-specification-20070704.html.

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 use of bibleref to textual elements. The text enclosed by an element with a bibleref attribute SHOULD be a plain 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 (not the enclosed content) is what designates an element as a Bible reference.

Consistent with the (X)HTML specification, other class attributes MAY be included along with bibleref (for styling or other purposes).

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 element that uses the bibleref class attribute. However, if the content cannot be easily and 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

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.

The title attribute format specification also allows discontinuous spans of verses within the same book to be indicated as a single reference, where the component spans are separated by a comma or semi-colon. For example, a reference like "2Tim 2:14-19, 3:16-17" can be marked as a single reference, though the title attribute should be used to clarify, as follows:

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

Discontinuous spans that are not within the same book should each be marked as distinct references.

Title Attribute Grammar

The textual content enclosed by the element that uses the bibleref class attribute is not constrained by the specification, though authors are encouraged to use text that follows conventional formats for Bible references. However, the format of the title attribute is constrained to the following grammar, to ensure that processors can successfully determine the intended reference.

<sep> := (' ' | '.' | ':')

<refsep> := (',' | ';')

<subbookref> := Chapter[<sep>Verse]

<simple> := Book[<sep><subbookref>]

<range> := Book<sep><subbookref>'-'<subbookref>

<reference> := [Version<sep>]( <simple> | <range> ) [ ( <refsep> <subbookref>['-'<subbookref>] )* ]

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.

Verse

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

Processors MUST allow any combination of spaces, periods, and colons for <sep>, e.g. "2Tim 2:15", "2Tim.2.15", "2Tim 2 15".

Additional whitespace is allowed between elements.

A bibleref processor is any automated mechanism which processes pages with bibleref markup to:

1. identify the elements that are Bible references, and
2. specify the intended references

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. In general, processors MAY produce output that differs in formatting from the original textual content or the title attribute, provided the references are still equivalent.

Handling Non-Standard and Invalid Data

If a processor cannot determine the intended reference from either the enclosed text or a title attribute if one is supplied, the processor MUST report the presence of a reference, and MAY return an empty string for the reference itself.

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), and whether a given verse number is valid for the referenced chapter. The processor MAY return an empty string for references with invalid book, chapter or verse designators.

Since Bible versions are an open set (more are added over time), the processor MUST include the version designator if it is provided in the title attribute, even if it is invalid or unrecognized. Processors MAY omit an unrecognized version identifier if it's non-standard and not included in the title.

This page contains a variety of examples of different kinds of bibleref markup, and the intended output according to the specification. Developers of bibleref processors are encouraged to test their implementations against this and other test suites to ensure full coverage.

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.

These previous versions are superceded by the current version, but retained here for reference.

• 2007 June 12 version