Support a defined set of additional attributes for element <char> for assigning linking properties.
See also USX 3.0 proposal for "Link text (add para@style jmp)" (#23)
This is the USX companion to USFM 3.0 proposal "Syntax for assigning word-level linking attributes". See: ubsicap/usfm#25 for detail.
General Syntax
Linking attributes are added to elements using standard XML syntax. Names given to linking attributes begin with link-, distinguishing them from any other descriptive attributes (#18).
Linking attributes are combined with any other descriptive attributes added to the same marker. The order of attributes is not significant, although it would benefit readability to have descriptive and linking attributes grouped together.
Proposed Attribute List
link-href - identifies the resource being linked to as a URI.
Additional USFM specified URI prefixes are:
prj: + Book, chapter, and verse locator within a Paratext project expressed in the form <project/resource_name> + reference using standard USFM / USX scripture reference syntax. Example: prj:RSV52 MAT 3:1-4
A link reference within the same project text does not require a URI prefix but must follow the standard USFM / USX scripture reference syntax. Example: MAT 3:1-4.
The resource may be identified by unique id. Example: #article-Ruth or prj:GNTSB #article-Ruth
link-title - plain text describing the remote resource such as might be shown in a tooltip.
link-id - a unique identifier for this location (an anchor).
The set of URI prefixes used within a link-href attribute can be extended beyond the predefined set for USX 3.0. Any user defined URI prefixes must begin with the prefix x-.
Examples
Link to other project text
The traditional translation of verse 1, as given in
<char style="jmp" link-href="prj:RSV52 GEN 1:1" link-title="Revised Standard
Version">RSV</char>, may be quite appropriate.
Link to illustration / media
Storehouses, as used here, refers to large buildings with walls and roof, where grain was
kept until needed. (See illustration: <char style="jmp" link-href="figures/storehouse.png"
link-title="Ancient storehouse">Storehouse</char>)
Assigning an identifier (anchor). In this example the markup is a milestone, indicating a location but not marking text.
<para style="q1">“Someone is shouting in the desert,</para>
<para style="q2">‘Prepare a road for the Lord;</para>
<para style="q2">make a straight path for him to travel!’ ”</para>
<sidebar style="esb" category="people">
<para style="ms"><char style="jmp" link-id="article-john_the_baptist" />John the
Baptist</para>
<para style="p">John is sometimes called the last “Old Testament prophet” because of the
warnings he brought about God's judgment and because he announced the coming of God's
“Chosen One” (Messiah).</para>
</sidebar>
Glossary entry including a link reference to an external URL
<para style="p"><verse number="2-6a" style="v"/>From Abraham to King David, the
following ancestors are listed: Abraham, Isaac, Jacob, Judah and his brothers; then Perez and
Zerah (their mother was Tamar), Hezron, Ram, Amminadab, Nahshon, Salmon, Boaz (his mother
was Rahab), Obed (his mother was <char style="jmp" link-href="#article-Ruth">Ruth</char>),
Jesse, and King David.
Nested within footnote text
<note caller="-" style="ef"><char style="fr">1.2-6a: </char><char style="fq">Ruth: </char>
<char style="ft">A Moabite. Only outstanding women were normally included in Jewish
genealogical lists. See article on <char style="jmp" link-href="#article-Ruth">Ruth</char>
</note>
Proposal
<char>
for assigning linking properties.This is the USX companion to USFM 3.0 proposal "Syntax for assigning word-level linking attributes". See: ubsicap/usfm#25 for detail.
General Syntax
Linking attributes are added to elements using standard XML syntax. Names given to linking attributes begin with
link-
, distinguishing them from any other descriptive attributes (#18).Linking attributes are combined with any other descriptive attributes added to the same marker. The order of attributes is not significant, although it would benefit readability to have descriptive and linking attributes grouped together.
Proposed Attribute List
link-href
- identifies the resource being linked to as a URI.prj:
+ Book, chapter, and verse locator within a Paratext project expressed in the form <project/resource_name> + reference using standard USFM / USX scripture reference syntax. Example:prj:RSV52 MAT 3:1-4
MAT 3:1-4
.#article-Ruth
orprj:GNTSB #article-Ruth
link-title
- plain text describing the remote resource such as might be shown in a tooltip.link-id
- a unique identifier for this location (an anchor).The set of URI prefixes used within a
link-href
attribute can be extended beyond the predefined set for USX 3.0. Any user defined URI prefixes must begin with the prefixx-
.Examples
Link to other project text
Link to illustration / media
Assigning an identifier (anchor). In this example the markup is a milestone, indicating a location but not marking text.
Glossary entry including a link reference to an external URL
Reference to named target (in same project)
Nested within footnote text