New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Linking attribute for \xt ...\xt* (add link-href as default) #41

Closed
DavidHaslam opened this Issue Jan 2, 2017 · 8 comments

Comments

Projects
None yet
2 participants
@DavidHaslam

DavidHaslam commented Jan 2, 2017

The example in the User Reference documentation for \cd has several verse numbers within the chapter description.

Genesis 1 (Russian Synodal, Protestant Version)
\cd 1 Бог благословляет седьмой день; 8 человек в раю Едемском; четыре реки; дерево познания добра и зла. 18 Человек дает названия животным. 21 Создание женщины.

Other historic Bible translations have the same feature.
One notable example is the 1769 Benjamin Blayney Oxford Edition of the KJV.
(PDF page 22 has Genesis 1).

For Bible software developers to take advantage of these verse numbers in order for the user to click on any one of them and jump straight to the corresponding verse, these should be marked at character level.

In mobile applications with small screens, this would be especially beneficial to skip scrolling once you've found the chapter in such translations.

I therefore propose that \cdt ...\cdt* be defined for this very purpose. The example would then become:

\cd \cdt 1\cdt* Бог благословляет седьмой день; \cdt 8\cdt* человек в раю Едемском; четыре реки; дерево познания добра и зла. \cdt 18\cdt* Человек дает названия животным. \cdt 21\cdt* Создание женщины.

NB. The final letter 't' in the marker denotes 'target' by analogy with how the word is used in \xt

@DavidHaslam DavidHaslam changed the title from Marking verse numbers within chapter descriptions (add \cdt ...\cd*) to Marking verse numbers within chapter descriptions (add \cdt ...\cdt*) Jan 2, 2017

@DavidHaslam

This comment has been minimized.

Show comment
Hide comment
@DavidHaslam

DavidHaslam Jan 2, 2017

Afterthought:

In principle, the ParaTExt consistency checking could be enhanced to verify that each marked verse number in a chapter description was within the bounds of the chapter.

DavidHaslam commented Jan 2, 2017

Afterthought:

In principle, the ParaTExt consistency checking could be enhanced to verify that each marked verse number in a chapter description was within the bounds of the chapter.

@DavidHaslam

This comment has been minimized.

Show comment
Hide comment
@DavidHaslam

DavidHaslam Nov 29, 2017

@klassenjm - please review, thanks.

DavidHaslam commented Nov 29, 2017

@klassenjm - please review, thanks.

@DavidHaslam

This comment has been minimized.

Show comment
Hide comment
@DavidHaslam

DavidHaslam Dec 8, 2017

Please refer to #34 to gain the context for this comment.

As regards chapter-less verse references, especially when these occur without a prefix abbreviation (as some translators are wont in some footnotes), I wonder whether there should be a new character level marker defined for this purpose? i.e. Like \xt_...\xt* but just for verse numbers.

\xv_...\xv*

  • A reference to a verse number or verse range or sequence of verses, with generally wide scope.
  • Used only when the chapter number is not included. Reference target assumed to be in the current chapter.

This would solve this issue too, as a general purpose \xv would make \cdt redundant.

DavidHaslam commented Dec 8, 2017

Please refer to #34 to gain the context for this comment.

As regards chapter-less verse references, especially when these occur without a prefix abbreviation (as some translators are wont in some footnotes), I wonder whether there should be a new character level marker defined for this purpose? i.e. Like \xt_...\xt* but just for verse numbers.

\xv_...\xv*

  • A reference to a verse number or verse range or sequence of verses, with generally wide scope.
  • Used only when the chapter number is not included. Reference target assumed to be in the current chapter.

This would solve this issue too, as a general purpose \xv would make \cdt redundant.

@DavidHaslam

This comment has been minimized.

Show comment
Hide comment
@DavidHaslam

DavidHaslam Dec 8, 2017

Background: @klassenjm (email to yours truly)

The implementation in Paratext 8 for evaluating \xt treats references without book abbreviations as being to the same book.
It treats numbers without a chapter / verse separator as being to that chapter in the current book (verseless reference).

There is no support for a chapterless reference (it would be ambiguous with verseless reference -- unless there was a regular syntax to specify a character or abbreviation for verse, like "v13" - which there is not right now).

DavidHaslam commented Dec 8, 2017

Background: @klassenjm (email to yours truly)

The implementation in Paratext 8 for evaluating \xt treats references without book abbreviations as being to the same book.
It treats numbers without a chapter / verse separator as being to that chapter in the current book (verseless reference).

There is no support for a chapterless reference (it would be ambiguous with verseless reference -- unless there was a regular syntax to specify a character or abbreviation for verse, like "v13" - which there is not right now).

@klassenjm

This comment has been minimized.

Show comment
Hide comment
@klassenjm

klassenjm Apr 11, 2018

Contributor

As David suggests, it would be redundant to add another marker to USFM to indicate a target reference.

Adding another type of target reference marker (\xv ...\xv*) is also awkward.

In the existing USFM 3.0 spec, if a project was only interest in marking the verse numbers, they could use \vp ...\vp* for this need.

In order to specify a link at this location, it could be extended with \vp 3|link-href="MAT 1:18"\vp* (to indicate a link to verse 18), which is somewhat odd and awkward, since most other situations, the user could use \xt ...\xt*

\xt ...\xt* could be expanded to allow specifying that only a verse is found in the this target, like \xt v18\vp*, but this becomes difficult because of the variations which could occur in how verse (v) should be expressed. \xt :3\xt* could be a reasonable option, or should always be considered a mistake.

This is going to remain in the backlog for now. An update will be made to the official USFM stylesheet for Paratext to allow \vp ...\vp* within \cd paragraphs.

Contributor

klassenjm commented Apr 11, 2018

As David suggests, it would be redundant to add another marker to USFM to indicate a target reference.

Adding another type of target reference marker (\xv ...\xv*) is also awkward.

In the existing USFM 3.0 spec, if a project was only interest in marking the verse numbers, they could use \vp ...\vp* for this need.

In order to specify a link at this location, it could be extended with \vp 3|link-href="MAT 1:18"\vp* (to indicate a link to verse 18), which is somewhat odd and awkward, since most other situations, the user could use \xt ...\xt*

\xt ...\xt* could be expanded to allow specifying that only a verse is found in the this target, like \xt v18\vp*, but this becomes difficult because of the variations which could occur in how verse (v) should be expressed. \xt :3\xt* could be a reasonable option, or should always be considered a mistake.

This is going to remain in the backlog for now. An update will be made to the official USFM stylesheet for Paratext to allow \vp ...\vp* within \cd paragraphs.

@klassenjm

This comment has been minimized.

Show comment
Hide comment
@klassenjm

klassenjm Apr 11, 2018

Contributor

Maybe \xt could have an optional reference to be parsed: \xt 3|MAT 3:3\xt* (and allow \xt verse 3|MAT 3:3\xt*) and the references check could just check the reference part?

This would make \xt more flexible, and allow a common method for simple target references.

Contributor

klassenjm commented Apr 11, 2018

Maybe \xt could have an optional reference to be parsed: \xt 3|MAT 3:3\xt* (and allow \xt verse 3|MAT 3:3\xt*) and the references check could just check the reference part?

This would make \xt more flexible, and allow a common method for simple target references.

@DavidHaslam

This comment has been minimized.

Show comment
Hide comment
@DavidHaslam

DavidHaslam Apr 12, 2018

That would make the verse number display as a superscripted xref, yet we require the verse number to be the same style as the rest of the chapter description, with the added property of being a link.

DavidHaslam commented Apr 12, 2018

That would make the verse number display as a superscripted xref, yet we require the verse number to be the same style as the rest of the chapter description, with the added property of being a link.

@klassenjm

This comment has been minimized.

Show comment
Hide comment
@klassenjm

klassenjm Apr 13, 2018

Contributor

@DavidHaslam It could look that way, but it's a matter of how you define the appearance of \vp.

The latter comment about \xt is the course I think makes more sense. It makes it possible to use \xt ...\xt* for pointing a scripture reference targets more flexibly. In the same way that a couple character level markers have a default attribute in USFM 3, the default attribute for \xt ...\xt* would be link-href, meaning you can provide the standard reference that some non-standard reference text is pointing to.

So:

\cd \xt 1|GEN 1:1\xt* Бог благословляет седьмой день; \xt 8|GEN 1:8\x* человек в раю 
Едемском; четыре реки; дерево познания добра и зла. \xt 18|GEN 1:18\x* Человек дает 
названия животным. \xt 21|GEN 1:21\x* Создание женщины.

or the other examples suggested earlier.

It would not need to be written in the longer form of \xt 21\link-href="GEN 1:21"\xt*

Contributor

klassenjm commented Apr 13, 2018

@DavidHaslam It could look that way, but it's a matter of how you define the appearance of \vp.

The latter comment about \xt is the course I think makes more sense. It makes it possible to use \xt ...\xt* for pointing a scripture reference targets more flexibly. In the same way that a couple character level markers have a default attribute in USFM 3, the default attribute for \xt ...\xt* would be link-href, meaning you can provide the standard reference that some non-standard reference text is pointing to.

So:

\cd \xt 1|GEN 1:1\xt* Бог благословляет седьмой день; \xt 8|GEN 1:8\x* человек в раю 
Едемском; четыре реки; дерево познания добра и зла. \xt 18|GEN 1:18\x* Человек дает 
названия животным. \xt 21|GEN 1:21\x* Создание женщины.

or the other examples suggested earlier.

It would not need to be written in the longer form of \xt 21\link-href="GEN 1:21"\xt*

@klassenjm klassenjm changed the title from Marking verse numbers within chapter descriptions (add \cdt ...\cdt*) to Linking attribute for target references (add link-href as default) Apr 13, 2018

@klassenjm klassenjm changed the title from Linking attribute for target references (add link-href as default) to Linking attribute for \xt ...\xt* (add link-href as default) Apr 13, 2018

@klassenjm klassenjm added attribute type-note and removed marker labels Apr 13, 2018

@klassenjm klassenjm added this to the 3.0.0 milestone Apr 13, 2018

@klassenjm klassenjm closed this Apr 13, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment