Scripture Reference Settings needed for roundtrip between USFM and USX

[KentSpiel]

What is the relationship between the Scripture Reference Settings and the USFM standards. I assume these are considered business rules. Nevertheless to convert from USFM to valid USX the USFM verse number must be decoded in order to create a valid sid and eid. In other words round tripping is not possible without the Scripture Reference Settings information. Should this be stated in the specification? Should USFM provide a place for this information in metadata?

[klassenjm]

Hi @KentSpiel -- The sid and eid attributes use only the USFM-USX standard book abbreviations. Unless I'm not following your concern, I don't think a reference to a PT project's scripture reference settings is needed.

[KentSpiel]

I am not referring to @sid and @eid I am concerned with links like (\+xt см. Исх. 3:13–15\+xt*). Without the Scripture Reference settings you can't create the location attribute in USX (<char style="xt">см. <ref loc="EXO 3:13-15">Исх. 3:13–15</ref></char>). In the example here you can convert `Mk 1.24;

Lk 2.39 Jn 1.45.` to ` \xt Mrk 1.24; Luk 2.39; Jhn 1.45.` but, without the Scripture reference settings, you cannot convert the other way around. That is why I mention 'roundtrip' in the issue title. A second concern is that `@loc` is referred to as `@link-href`. I see the same function but I am not sure why there is a different attribute. Am I missing something?

[mhosken]

I am not referring to @sid and @eid I am concerned with links like (+xt см. Исх. 3:13–15+xt*). Without reference to the Scripture Reference settings you can't create the USX (см. Исх. 3:13–15).

I see the problem now. What we need is a \ref marker in USFM, such that your example would become: \xt CM. \ref Ncx. 3:13-15|loc="EXO 3:13-15"\ref\xt perhaps simplified to remove the loc= since it would be the default attribute.

I'm assuming folk are happy that a reference acts like a char style?

Are we happy to approve my adding this to the grammar?

In the example here https://docs.usfm.bible/usfm-usx-docs/latest/char/notes/crossref/xt.html you can convert Mk 1.24; Lk 2.39 Jn 1.45. to \xt Mrk 1.24; Luk 2.39; Jhn 1.45. but not the other way around without the Scripture reference settings.

I would also like to extend loc to be a reference list instead if just a single reference. Thus the above would become \xt \ref Mk 1.24; Lk 2.39; Jn 1.45 |loc= "MRK 1:24; LUK 2:39; JHN 1:45"\ref.\xt

What say ye to that?

Please can everyone on the committee respond. I don't think we should proceed outside of a meeting unless we have 100% agreement.

[jwickberg]

The <ref> element was added to USX to support clickable links for references in digital publications, so making it a reference list would not match the original intent of the element.

I've sometimes thought that it would be easier for Paratext users if they could select the verse(s) that they want and the vernacular text would be generated. Having the \ref marker defined would make this easier to implement, since you would have both forms of the reference in the USFM.

So, I'm in favor of including \ref, but I think the value of the loc attribute should be a single reference.

[jonathanrobie]

I would also like to extend loc to be a reference list instead if just a single reference. Thus the above would become \xt \ref Mk 1.24; Lk 2.39; Jn 1.45 |loc= "MRK 1:24; LUK 2:39; JHN 1:45"\ref.\xt

I'm thinking of equivalents in HTML and Markdown ...

<a href="location.com/here">Link text</a>

[Link text](location.com/here)

Should we choose a syntax that says the semantics are similar here? Should each ref have an optional text, and the default text is the ref itself?

[klassenjm]

I see the problem now. What we need is a \ref marker in USFM, such that your example would become: \xt CM. \ref Ncx. 3:13-15|loc="EXO 3:13-15"\ref\xt perhaps simplified to remove the loc= since it would be the default attribute.

Just to have this in view in our discussion -- the USFM spec 3.0 provided an \xta marker to mark the added text, like CM. So, using \xta this example would be marked like:

\x - \xo #:# \xta CM. \xt Ncx. 3:13-15\xt*\x*

assuming that the Ncx. 3:13-15 was a prescribed reference format for this text (book names and punctuation). If not, then it would be:

\x - \xo #:# \xta CM. \xt Ncx. 3:13-15|EXO 3:13-15\x*

https://docs.usfm.bible/usfm-usx-docs/latest/char/notes/crossref/xta.html

[KentSpiel]

This seems like a fair solution. So a USX document with loc="" references could/should be imported into Paratext with the location info included after |. It would then be up to the user to provide the Scripture Reference information so that the loc information is not necessary and remove the reference markup if desired.

[KentSpiel]

Based on this discussion I don't see the need for any changes to the Standard. This is an implementation issue. I have resolved this issue.