Character Marker Nesting

Background

Character level markup is applied to a span of text within a paragraph block. Sometimes, marking texts in a semantically accurate way requires nesting a character level element within another character level element. In these situations an editor, processor, or publishing system must be able to interpret the nested markup contexts correctly.

Initially, USFM did not allow character styles to be nested. Whenever a new character style was encountered in a paragraph the currently active character style was implicitly closed. However, it is a common occurrence for text within footnote sections, a footnote quotation (fq), keyword (fk), or the footnote text (ft) to contain some text that needs to be marked. With the character styles being implicitly closed, a new way of marking nesting was needed and the plus sign + was used as a prefix to the opening and closing forms of a nested marker pair.

With USFM 3.1, the ending character marker has been made required — except for the markers used to start sections in footnotes and cross references (the note’s 'structural elements'). This allows nesting to be done without the use of the plus sign. For backward compatibility, the use of the plus sign will still be processed as it has been.

In the following example text:

\nd indicates to start a new character element nested inside the existing \add element (without closing \add)
\nd* indicates the end of the nested environment without closing \add

USFM
USX
USJ

\p The following is a \add translator's addition containing the
word \nd Lord\nd* within it\add* ...

<para style="p">The following is a <char style="add">translator's addition
  containing the word <char style="nd">Lord</char> within it</char> ...</para>

{
  "type": "para",
  "marker": "p",
  "content": [
    "The following is a",
    {
      "type": "char",
      "marker": "add",
      "content": [
        "translator's addition containing the word",
        {
          "type": "char",
          "marker": "nd",
          "content": ["Lord"]
        },
        " within it"
      ]
    },
    " ..."
  ]
}

Multiple levels of nesting can occur.

In USX, nested elements occur in XML without requiring any additional syntax.

Examples

USFM
USX
USJ

Example 1. Numbers 21.14 (GNT) - bk + nd nested

\v 14 That is why \bk The Book of the \nd Lord\nd*'s Battles\bk* speaks of
“...the town of Waheb in the area of Suphah, and the valleys; the Arnon River,

Example 2. Numbers 21.14 (GNT) - bk + nd nested

<para style="p">...<verse number="14" style="v" sid="NUM 21:14"/>That is why <char
    style="bk">The Book of the <char style="nd">Lord</char>'s Battles</char>
  speaks of “...the town of Waheb in the area of Suphah, and the valleys; the
  Arnon River, <verse eid="NUM 22:14"/></para>

Example 3. Numbers 21.14 (GNT) - bk + nd nested

{
  "type": "para",
  "marker": "p",
  "content": [
    "...",
    {
      "type": "verse",
      "marker": "v",
      "number": "14",
      "sid": "NUM 21:14"
    },
    "That is why ",
    {
      "type": "char",
      "marker": "bk",
      "content": [
        "The Book of the",
        {
          "type": "char",
          "marker": "nd",
          "content": ["Lord"]
        },
        "'s Battles"
      ]
    },
    " speaks of “...the town of Waheb in the area of Suphah, and the valleys; the Arnon River, "
  ]
}

$Numbers 21.14 (GNT) - \bk \nd nested$

USFM
USX
USJ

Example 4. Genesis 2.4 (GNT) - fk and ft + nd nested

\p When the \nd Lord\nd* \f + \fr 2.4: \fk the \nd Lord\nd*: \ft Where the
Hebrew text has Yahweh, traditionally transliterated as Jehovah, this
translation employs \nd Lord\nd* with capital letters, following a usage
which is widespread in English versions.\f* God made the universe,
...

Example 5. Genesis 2.4 (GNT) - fk and ft + nd nested

<para style="p" vid="GEN 2:4">When the <char style="nd">Lord</char>
  <note caller="+" style="f">
    <char style="fr" closed="false">2.4: </char>
    <char style="fk" closed="false">the
      <char style="nd">Lord</char>:
    </char>
    <char style="ft" closed="false">Where the Hebrew text has Yahweh,
    traditionally transliterated as Jehovah, this translation employs
      <char style="nd">Lord</char> with capital letters, following a usage
      which is widespread in English versions.
    </char>
  </note> God made the universe, <verse eid="GEN 2:4" />

Example 6. Genesis 2.4 (GNT) - fk and ft + nd nested

{
  "type": "USJ",
  "marker": "p",
  "content": [
    "When the",
    {
      "type": "char",
      "marker": "nd",
      "content": ["Lord"]
    },
    {
      "type": "note",
      "marker": "f",
      "caller": "+",
      "content": [
        {
          "type": "char",
          "marker": "fr",
          "content": ["2.4:"]
        },
        {
          "type": "char",
          "marker": "fk",
          "content": [
            "the",
            {
              "type": "char",
              "marker": "nd",
              "content": ["Lord"]
            },
            ": "
          ]
        },
        {
          "type": "char",
          "marker": "ft",
          "content": [
            "Where the Hebrew text has Yahweh, traditionally transliterated as Jehovah, this translation employs",
            {
              "type": "char",
              "marker": "nd",
              "content": ["Lord"]
            },
            " with capital letters, following a usage which is widespread in English versions. "
          ]
        }
      ]
    },
    " God made the universe, ",
    "..."
  ]
}