Cross References¶

Cross Reference Container

Cross references are entered inline within the main scripture body text. The boundaries of the cross reference text are defined by an opening and closing marker. The individual elements which make up the cross reference content are described under the heading Cross Reference Content Elements below.

\x …\x*¶

Syntax: \x_+_(\xo_REF_)cross reference content\x*
Type: note
Added: 1.0
Use: Beginning and ending of the cross reference element.

+

The cross reference caller, which may be one of the following three types:

+ – indicates that the caller should be generated automatically by the translation editor, or publishing tools.
- – indicates that no caller should be generated, and is not used.
? – where ? represents the character to be used for the caller. The caller is defined for the specific cross reference by the author.

cross reference content (see below)

All of the text elements which make up the cross reference:

origin reference

special cross reference elements such as keywords or quotations

target references

Each element should be prefixed by the appropriate marker (listed below).

Note

Important: See Syntax Notes for addition information on the use of endmarkers for elements within cross reference content.

Cross Reference Content Elements¶

The following markup can be included as part of the cross reference content:

\xo¶

Syntax: \xo_##SEP##
Type: character (note)
Added: 1.0
Use: Cross reference origin reference.
This is the chapter and verse(s) that target reference(s) are being provided for.
SEP indicates where the appropriate chapter/verse separator should be used (i.e. colon “:”, full stop “.” etc.)

\xk¶

Syntax: \\xk_text...
Type: character (note)
Added: 1.0
Use: A keyword from the scripture translation text which the target reference(s) also refer to.

\xq¶

Syntax: \xq_text...
Type: character (note)
Added: 1.0
Use: A quotation from the scripture text.
Use of a quotation would be intended to help the reader to understand the portion of text (or concept) for which the target reference(s) are being supplied.

\xt¶

Syntax: \\xt_refs...
Type: character (note)
Added: 1.0
Updated: 3.0 (attributes)
Use: Target reference(s).
A list of scripture references, commonly provided as book name abbreviations plus chapter and verse, or range of verses. The punctuation used between chapter and verse, reference ranges, and between target references can differ significantly across texts.

Text and Formatting Samples - Typical Cross Reference - Matthew 2.23 (GNT)

\p
\v 22 But when Joseph heard that Archelaus had succeeded his father Herod as king of
Judea, he was afraid to go there. He was given more instructions in a dream, so he went
to the province of Galilee
\v 23 \x - \xo 2.23: \xt Mrk 1.24; Luk 2.39; Jhn 1.45.\x* and made his home in a town
named Nazareth. And so what the prophets had said came true: “He will be called a
Nazarene.”

Multiple Origin Parts - Mark 10.19 (GNT)

\p
\v 18 “Why do you call me good?” Jesus asked him. “No one is good except God alone.
\v 19 \x - \xo 10.19: a \xt Exo 20.13; Deu 5.17; \xo b \xt Exo 20.14; Deu 5.18; \xo c
\xt Exo 20.15; Deu 5.19; \xo d \xt Exo 20.16; Deu 5.20; \xo e \xt Exo 20.12; Deu 5.16.\x*
You know the commandments: ‘Do not commit murder; do not commit adultery; do not steal;
do not accuse anyone falsely; do not cheat; respect your father and your mother.’”

Attributes

Following the syntax for word level attributes and the definitions for linking attributes, \xt ...\xt provides the linking attribute link-href as a default attribute.

link-href: Unambiguously identifies the scripture target reference using a standard scripture reference format. (default)
Book names must be one a standard book identifier. Chapter verse separator is always a colon :. A string of pattern [A-Z1-4]{3} ?[a-z0-9\-,:]*

In some scenarios a target reference is written in a format which cannot be accurately parsed and identified. Providing the link-href attribute allows greater flexibility in the use of \xt ...\xt*.

In this context, link-href should only target scripture references for the current text (i.e. references to other project texts or non-scripture URIs are not allowed)

When adding link-href, the explicit attribute name is not required since it is defined in USFM as the default for \xt ...\xt*.

Text Sample - Genesis 2 (Russian Synodal, Protestant Version, extending the sample for \cd - chapter description)

\c 2
\cd \xt 1|GEN 2:1\xt* Бог благословляет седьмой день; \xt 8|GEN 2:8\x* человек в раю Едемском;
четыре реки; дерево познания добра и зла. \xt 18|GEN 2:18\x* Человек дает названия животным.
\xt 21|GEN 2:21\xt* Создание женщины.
\p
\v 1 Так совершены небо и земля и все воинство их.
\p
\v 2 И совершил Бог к седьмому дню дела Свои, которые Он делал, и почил в день седьмой
от всех дел Своих, которые делал.

A number (7) alone marked with \xt ...\xt* is ambiguous, since it could refer to chapter 7 or verse 7 (in Paratext, a number alone is interpreted as a chapter reference). Extending \xt ...\xt* with the link-ref attribute makes it possible to express the target reference unambiguously.

\xt 7|MAT 6:7\xt*
\xt verse 7|MAT 6:7\xt*
\xt v7|MAT 6:7\xt*

\xta¶

Syntax: \\xta_text...
Type: character (note)
Added: 3.0
Use: Target reference(s) extra / added text.
Used for marking text which should be ignored when identifying or linking to cross reference target references.

Text and Formatting Sample - Matthew 3.0 (GNT - text and markup adapted)

\c 3
\s1 The Preaching of John the Baptist\x - \xo 3.0 \xta Compare with \xt Mk 1.1-8;
Lk 3.1-18; \xta and \xt Jn 1.19-28 \xta parallel passages.\x*
\p
\v 1 At that time John the Baptist came to the desert of Judea and started preaching.

\xop …\xop*¶

Syntax: \xop_text...\xop*
Type: character (note)
Added: 3.0
Use: Published cross reference origin text.
In some texts, the content intended to be published in the position of the cross reference origin text \xo does not follow the typical <chapter><separator><verse> pattern. An origin reference following this pattern is required for validation of the cross reference location. \xop ...\xop* can be used in order to supply the content intended for publishing, similar to the use of \cp and vp …vp*.

Text and Formatting Sample - Jonah 1.1-5 (Bulgarian Orthodox Bible)

\p
\v 1 \x - \xo 1:1 \xop Гл 1. (1)\xop* \xt 4 Царств. 14:25.\x*И биде слово Господне
към Иона, син Аматиев:
\v 2 \x - \xo 1:2 \xop (2)\xop* \xt Бит. 10:11. Иона 3:3.\x*„стани, иди в Ниневия,
град голям, и проповядвай в него, защото злодеянията му достигнаха до Мене“.
\v 3 И стана Иона да побегне в Тарсис от лицето Господне; дойде в Иопия и намери кораб,
който отиваше за Тарсис, плати за превоз и влезе в него, за да отплува с тях в Тарсис
от лицето Господне.
\v 4 \x - \xo 1:4 \xop (4)\xop* \xt Пс. 106:25.\x*Но Господ подигна в морето силен
вятър, и стана в морето голяма буря, и корабът насмалко оставаше да се разбие.
\v 5 \x - \xo 1:5 \xop (5)\xop* \xt 4 Царств. 17:29.\x*Уплашиха се корабниците; те
викаха всеки към своя бог и почнаха да хвърлят в морето товара от кораба, за да му
олекне от него; а Иона бе слязъл в дъното на кораба, бе легнал и дълбоко заспал.

\xot …\xot*¶

Syntax: \xot_refs...\xot*
Type: character (note)
Added: 2.2
Use: References (or other text) between these markers is material to be included only in published editions that contain the Old Testament books. (optional)

\xnt …\xnt*¶

Syntax: \xnt_refs...\xnt*
Type: character (note)
Added: 2.2
Use: References (or other text) between these markers is material to be included only in published editions that contain the New Testament books. (optional)

\xdc …\xdc*¶

Syntax: \xdc_refs...\xdc*
Type: character (note)
Added: 1.0
Deprecated: 3.0
Use: References (or other text) between these markers is material to be included only in published editions that contain the Deuterocanonical books.|br| Deprecated (use is discouraged).

Recommended alternate: General purpose use of \dc …\dc* or nested \+dc ...\+dc* wherever DC-only content is being marked.

Text and Formatting Samples - Psalm 115.3-4 (GNT - cross references)

\q1
\v 3 Our God is in heaven;
\q2 he does whatever he wishes.
\q1
\v 4 \x - \xo 115.4-8: \xt Ps 135.15-18; \xdc Ltj Jr 4-73; \xt Rev 9.20.\x* Their
gods are made of silver and gold,
\q2 formed by human hands.

1 Corinthians 15.51-52 (GNT - cross reference)

\p
\v 51-52 \x - \xo 15.51,52: \xdc 2Es 6.23; \xt 1Th 4.15-17.\x* Listen to this secret
truth: we shall not all die, but when the last trumpet sounds, we shall all be changed
in an instant, as quickly as the blinking of an eye. For when the trumpet sounds, the
dead will be raised, never to die again, and we shall all be changed.

\rq …\rq*¶

Syntax: \rq ...\rq*
Type: character
Added: 2.05
Use: Inline quotation reference(s).
See details and examples in Titles, Heading, and Labels