{"id":20,"date":"2007-05-26T11:37:46","date_gmt":"2007-05-26T15:37:46","guid":{"rendered":"http:\/\/www.openbible.info\/blog\/2007\/05\/bible-microformats\/"},"modified":"2007-05-26T11:37:46","modified_gmt":"2007-05-26T15:37:46","slug":"bible-microformats","status":"publish","type":"post","link":"https:\/\/www.openbible.info\/blog\/2007\/05\/bible-microformats\/","title":{"rendered":"Bible Microformats"},"content":{"rendered":"

Sean from Blogos proposes a microformat for marking up Bible references<\/a> on the web.<\/p>\n

About Microformats<\/h3>\n

Microformats<\/a> are a way of marking up semantic data in HTML without inventing new elements or attributes. For example, here\u2019s how you might mark up geographic coordinates<\/a>:<\/p>\n

<div class=\"geo\">GEO: <span class=\"latitude\">37.386013<\/span>, <span class=\"longitude\">-122.082932<\/span><\/div><\/code><\/p>\n

In this way, computer programs can figure out without any ambiguity that the above sequence of numbers refers to latitude and longitude. Browsers, for example, might automatically link the coordinates to Google Maps or your mapping application of choice. Firefox 3 is evolving along these lines<\/a>.<\/p>\n

Bible Microformat<\/h3>\n

I\u2019ve been thinking for a while about the best syntax to use for a Bible microformat. The problem I kept running into was in coming up with the One True Representation of a Bible verse (i.e., is it \u201cJohn 3:16\u201d or \u201cJn 3:16\u201d or \u201cJohn.3.16\u201d or something else).<\/p>\n

Sean neatly sidesteps the problem with a \u201cgood enough\u201d solution. He proposes a format akin to the following:<\/p>\n

<abbr class="bibleref" title="John 3:16">Jn 3:16<\/abbr><\/code><\/p>\n

The crucial aspect is that it doesn\u2019t matter exactly how you specify the Bible verse\u2014once you do the hard part of indicating that a string of text is a verse reference (the class="bibleref"<\/code>), any decent reference parser should be able to figure out which verses you mean. It\u2019s so simple it\u2019s brilliant.<\/p>\n

Now let\u2019s push it a little further.<\/p>\n

I suggest that the microformat should take advantage of the underused and, in this case, semantically more meaningful <cite><\/code> tag rather than the <abbr><\/code> tag. You are, after all, citing the Bible.<\/p>\n

<cite class="bibleref">John 3:16<\/cite><\/code><\/p>\n

However, you also have to account for people who link the verse to their favorite online Bible. You could double-up the tags:<\/p>\n

<a href="\u2026"><cite class="bibleref">John 3:16<\/cite><\/a><\/code><\/p>\n

But it\u2019s messier than need be. Since the practice of linking is widespread, why not overload the <a><\/code> tag with the appropriate class<\/code>:<\/p>\n

<a href="\u2026" class="bibleref">John 3:16<\/a><\/code><\/p>\n

Both <cite><\/code> and <a><\/code> have a title<\/code> attribute in which you can place a human- (and machine-) readable version of the verse if you choose. The title<\/code> is optional as long as the verse reference is the only text inside the tag. Indeed, a title<\/code> is required only if the element\u2019s text is ambiguous (a verse without a chapter and book, for example, or completely unrelated text). (The practice of not recording duplicate information is the Don\u2019t Repeat Yourself<\/a> principle.) For example:<\/p>\n

<p>God <a href="\u2026" class="bibleref" title="John 3:16">loves<\/a> us.<\/p><\/code><\/p>\n

Corner Cases<\/h3>\n

So how would you specify a Bible translation if a specific translation were germane to the citation\u2019s context? (In theory, when you don\u2019t specify a translation, people consuming the microformat could choose to see the passage in the translation of their choice, similar to how some people prefer to look up an address in Google Maps, while others prefer Yahoo Maps.) I\u2019m sympathetic to the OSIS<\/a> practice of indicating the translation first, followed by the reference. For example:<\/p>\n

<cite class="bibleref" title="ESV: John 3:16">Jn 3:16<\/cite><\/code><\/p>\n

This practice follows the logical progression of going from general to specific:<\/p>\n

[Implied Language] → Translation → Book → Chapter → Verse<\/p>\n

The title<\/code> is also human-readable, though it departs from the standard practice of placing the translation identifier after the reference.<\/p>\n

Sean mentions two other cases of note: verse ranges (e.g., \u201cJohn 3:16-17\u201d) and compound verses (e.g., \u201cJohn 3:16, 18, 20\u201d). Personally, I see no reason for a biblerefrange<\/code> attribute as he suggests. A bible reference parser should be able to handle a continuous range as easily as a single verse.<\/p>\n

But compound verses present a more complex problem. How do you mark them up? The above examples all stand on their own, which is one of the principles of microformats\u2014you parse the element and get everything you need. But let\u2019s say you have the text \u201cJohn 3:16, 18.\u201d Treating the range as a unit is easy:<\/p>\n

<cite class="bibleref">John 3:16, 18<\/cite><\/code><\/p>\n

Any parser will handle that text; though it could be ambiguous (do you mean John 3:16 and John 18?), in practice it rarely is. But what if you mark them up separately?<\/p>\n

<cite class="bibleref">John 3:16<cite>, <cite class="bibleref">18<\/cite><\/code><\/p>\n

In this case, the \u201c18\u201d doesn\u2019t communicate enough information to the parser. The parser could maintain a state and know that the previous reference was to John 3:16, but state requirements increase the parser\u2019s complexity, which in turn defeats the purpose of the microformat in the first place. In such cases, then, I would argue that a title<\/code> attribute is necessary:<\/p>\n

<cite class="bibleref">John 3:16<cite>, <cite class="bibleref" title="John 3:18">18<\/cite><\/code><\/p>\n

Putting It All Together<\/h3>\n

Here\u2019s my Bible microformat proposal:<\/p>\n

Citing a Bible Verse without Linking to It<\/h4>\n

<cite class="bibleref">[reference]<\/cite><\/code><\/p>\n

Citing a Bible Verse while Linking to It<\/h4>\n

<a class="bibleref">[reference]<\/a><\/code><\/p>\n

Citing a Bible Verse Indirectly (or When the Text Is Ambiguous) without Linking to It<\/h4>\n

<cite class="bibleref" title="[reference]">[any text]<\/cite><\/code><\/p>\n

Citing a Bible Verse Indirectly (or When the Link Text Is Ambiguous) while Linking to It<\/h4>\n

<a class="bibleref" title="[reference]">[any text]<\/a><\/code><\/p>\n

Verse Reference Format<\/h4>\n

The [reference] in the above examples refers to a machine-parsable and human-readable representation of a single verse, a range of verses, or a series of verses. You should use unambiguous abbreviations if you use abbreviations. See Appendix C in the OSIS spec <\/a> (pdf) for a list of possible abbreviations.<\/p>\n

When you\u2019re in doubt about whether the reference text is parsable, use the title<\/code> attribute to encode a fuller representation. In particular, when the reference doesn\u2019t include all the text necessary to produce an unambiguous book\/chapter\/verse reference, place an unambiguous reference in title<\/code>.<\/p>\n

About the title<\/code> Attribute<\/h4>\n

The title<\/code> attribute, when present, takes precedence over the contents of the element (<cite><\/code> or <a><\/code>). When the title<\/code> is not present, the contents of the element are assumed to be the verse reference. The title<\/code> attribute contains an unambiguous machine-parsable representation of the verse reference.<\/p>\n

The attribute can also contain an optional translation identifier at the beginning of the value, followed by a colon. Appendix D in the OSIS spec <\/a> (pdf) has a list of translation identifiers. For example:<\/p>\n

<cite title="ESV: John 3:16">\u2026<\/cite><\/code><\/p>\n

To be comprehensive, you would ideally include a language identifier (e.g., \u201cen:ESV: John 3:16<\/code>\u201d) before the translation identifier. I would argue that a language identifier is only necessary if you\u2019re using a non-standard abbreviation.<\/p>\n

However, you should only include a translation identifier if it is important that your readers see a particular translation or language. Otherwise, you should allow the parsing software to use your readers\u2019 preferred translation and language.<\/p>\n

Here is a Perl regex for allowed formats in the title<\/code>. $1<\/code> is the optional language identifier. $2<\/code> is the optional translation identifier. $3<\/code> is the verse reference, which is deliberately wide-open to accommodate many different reference formats.<\/p>\n

title="([\\w\\-]+:)?([\\w\\-]+:)?\\s*([^"]+)"<\/code><\/p>\n","protected":false},"excerpt":{"rendered":"

Sean from Blogos proposes a microformat for marking up Bible references on the web. About Microformats Microformats are a way of marking up semantic data in HTML without inventing new elements or attributes. For example, here\u2019s how you might mark up geographic coordinates: <div class=”geo”>GEO: <span class=”latitude”>37.386013<\/span>, <span class=”longitude”>-122.082932<\/span><\/div> In this way, computer programs can […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":[],"categories":[6],"tags":[],"_links":{"self":[{"href":"https:\/\/www.openbible.info\/blog\/wp-json\/wp\/v2\/posts\/20"}],"collection":[{"href":"https:\/\/www.openbible.info\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.openbible.info\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.openbible.info\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.openbible.info\/blog\/wp-json\/wp\/v2\/comments?post=20"}],"version-history":[{"count":1,"href":"https:\/\/www.openbible.info\/blog\/wp-json\/wp\/v2\/posts\/20\/revisions"}],"predecessor-version":[{"id":268,"href":"https:\/\/www.openbible.info\/blog\/wp-json\/wp\/v2\/posts\/20\/revisions\/268"}],"wp:attachment":[{"href":"https:\/\/www.openbible.info\/blog\/wp-json\/wp\/v2\/media?parent=20"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.openbible.info\/blog\/wp-json\/wp\/v2\/categories?post=20"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.openbible.info\/blog\/wp-json\/wp\/v2\/tags?post=20"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}