Good USFM with footnotes nested within words of Jesus

3 views
Skip to first unread message

Eric Chapman

unread,
Mar 20, 2022, 5:46:44 PMMar 20
to Teus Benschop

Hi, everybody,

I'm struggling to get my mind around USFM (example from John 2:4).

I want this:

Should look
      like

I use this USFM markup:

\v 4 Jėzus jai sako: \f + \fr 2:4 \ft „Kas man ir tau \add bendro\add* “ – Plg. ta pati gr. idioma (vns. „man ir tau“) Mk 5:7, Lk 8:28, Jn 2:4 ir dgs. („mums ir tau“) Mt 8:29, Mk 1:24, Lk 4:34. Panaši sandara vartojama Mt 27:19. Hbr. k. pasitaiko ši idioma Ts 11:12, II Sam 16:10, I Kar 17:18, II Kar 3:13, II Met 35:21.\f* \wj „Kas man ir tau \+add bendro\+add*, \f + \fr 2:4 \ft „moterie“ – Tai pagarbus būdas kreiptis, gal panašus į mūsų „Gerbiamoji“.\f* moterie? Mano valanda dar neatėjo.“\wj* 

This is what I get (Visual Editor). (1) There is an improper space after the first footnote caller. (2) not all of the verse is in red letter.

Visual
      editor

And when I select "Preview" it is even different from the Visual Editor's rendering:

Preview

What I would like to know is how does well-formed USFM look for this?

Thank you!

Eric


Robert Hunt

unread,
Mar 20, 2022, 7:14:33 PMMar 20
to bibledit...@googlegroups.com

Hi Eric,

On the USFM questions:

  1. Your USFM has a space before the first footnote caller "sako: \f" AND a space after the footnote caller "35:21.\f* \wj".

  2. You should close the wj before the footnote and reopen it afterwards, so "bendro\+add*,\wj* \f" and "„Gerbiamoji“.\f* \wj moterie?".

In general, you shouldn't have a space before \f markers if you want the footnote caller to apply to the previous word ("sako:" in this case).

In general, you should close and reopen wj fields whenever they're interrupted by any paragraph, footnote, or cross-reference marker, etc.

I'll leave others to answer the Bibledit questions.

Blessings,
Robert.

--
You received this message because you are subscribed to the Google Groups "Bibledit-General" group.
To unsubscribe from this group and stop receiving emails from it, send an email to bibledit-gener...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/bibledit-general/f1d55900-1af4-aced-3384-679e8ee0d20c%40etchapman.org.

Michael Johnson

unread,
Mar 20, 2022, 7:43:25 PMMar 20
to bibledit...@googlegroups.com

Hello, Eric.

Well-formed USFM for this example, assuming you want the footnote callers where you see them in the example, is:

\v 4 Jėzus jai sako: \f + \fr 2:4 \ft „Kas man ir tau \add bendro\add* “ – Plg. ta pati gr. idioma (vns. „man ir tau“) Mk 5:7, Lk 8:28, Jn 2:4 ir dgs. („mums ir tau“) Mt 8:29, Mk 1:24, Lk 4:34. Panaši sandara vartojama Mt 27:19. Hbr. k. pasitaiko ši idioma Ts 11:12, II Sam 16:10, I Kar 17:18, II Kar 3:13, II Met 35:21.\f* \wj „Kas man ir tau \+add bendro\+add*,\wj* \f + \fr 2:4 \ft „moterie“ – Tai pagarbus būdas kreiptis, gal panašus į mūsų „Gerbiamoji“.\f* \wj moterie? Mano valanda dar neatėjo.“\wj* 

For maximum compatibility with Bibledit, Paratext, and the Digital Bible Library, please note the following:

  • A bad quirk of both Paratext and the DBL is that text styles must stop before a footnote and be restarted (if appropriate) after the footnote. This is not logical to me, and I don't think Bibledit or Haiola care about this, but DBL compatibility is strongly recommended for eventual wider distribution of a Bible translation.
  • When starting Words of Jesus markup, note that the space after \wj is part of the markup, not part of the text. Therefore, if a space is required there, it should be before the "\wj ".
  • When ending Words of Jesus markup, note that no space is included in the end marker (\wj*). Therefore any space before or after this marker will be part of the text.
--
You received this message because you are subscribed to the Google Groups "Bibledit-General" group.
To unsubscribe from this group and stop receiving emails from it, send an email to bibledit-gener...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/bibledit-general/f1d55900-1af4-aced-3384-679e8ee0d20c%40etchapman.org.
--

Aloha,
Michael Johnson

26 HIWALANI LOOP • MAKAWAO HI 96768-8747
• USA
mljohnson.orgeBible.orgWorldEnglish.BiblePNG.Bible
Signal/Telegram/WhatsApp/Telephone: +1 808-333-6921
Skype: kahunapule • Telegram/Twitter: @kahunapule • Facebook: fb.me/kahunapule

Eric Chapman

unread,
Mar 20, 2022, 8:40:55 PMMar 20
to Teus Benschop

Michael, so is what you said as quoted below to be taken to mean there can be no text styles (aka character styles) in footnotes? Or am I misunderstanding you?

If that's the case, I'm not too sure I'm going to comply at this point. Maybe a forced-compliance change in the future could be done to get it within DBL's standards.

Thank you for your help!

Eric

Eric Chapman

unread,
Mar 20, 2022, 8:56:49 PMMar 20
to Teus Benschop

Hi, Robert,

Thank you! Regarding the wj markers, I guess my non-coder mind needs to think of them as "low-level" codes, maybe even ones that cannot be nested by use of the + sign?

Eric

Robert Hunt

unread,
Mar 20, 2022, 9:08:04 PMMar 20
to bibledit...@googlegroups.com

As Michael Johnson sort of said, USFM is not just the written standard, but also (the Paratext stylesheet and) what Paratext (and DBL) does. But without starting up Paratext, I suspect + character formats should be ok inside wj markers. But certainly a \p wouldn't and a \f or \x won't either.

And again as Michael said, when looking at raw USFM, always remember that THE FOLLOWING SPACE IS PART OF THE OPENING MARKER, but that doesn't apply to closing markers which finish with the asterisk.

BTW, there's a small group of us at https://github.com/Freely-Given-org/Bible_speaker_identification that hope to have software to tag automatically ALL quotations and utterances in Bible text. (Lots of details in the discussions there.) \wj is good for red letter Bibles, but much more powerful for study apps if we can agree on a way 1/ to tag Bible people and groups, and 2/ to markup speakers (and writers) and ALL quotations.

Robert.

--
You received this message because you are subscribed to the Google Groups "Bibledit-General" group.
To unsubscribe from this group and stop receiving emails from it, send an email to bibledit-gener...@googlegroups.com.

Michael Johnson

unread,
Mar 20, 2022, 9:17:55 PMMar 20
to bibledit...@googlegroups.com

No, I didn't say that there can be no text styles in footnotes. I said that text styles before the footnote need to be stopped before the footnote. Within the footnote, there can be additional footnotes. In an ideal world, that context switch would be fully automatic. There are two separate text streams: the main canonical text, and the footnotes/cross references/end notes. The text styles in the canonical text stream don't apply to the footnote text and vice versa.

One thing I could do to simulate that is to modify Haiola to automatically do that stop/restart of \wj formatting. That way, you don't have to worry about it. You still have to stop/restart \wj at verse boundaries for long quotes, like the Sermon on the Mount.

--
You received this message because you are subscribed to the Google Groups "Bibledit-General" group.
To unsubscribe from this group and stop receiving emails from it, send an email to bibledit-gener...@googlegroups.com.

Eric Chapman

unread,
Mar 20, 2022, 9:35:35 PMMar 20
to Teus Benschop

OK, I think I'm catching on. This is all new to me and doesn't seem too intuitive. :)

If you could get Haiola to go through and change what's there to correct USFM, that'd be great. Is that what you meant, or did you mean for the future?

Eric

Eric Chapman

unread,
Mar 26, 2022, 9:54:17 AMMar 26
to Teus Benschop

Hello, Robert, Michael and Teus,

In the Bible text we are preparing, we want to have the footnote markers before the word or phrase to which the footnote refers. I'm sure this is a rare typesetting policy, but does no other Bible at all do this? (Rhetorical question)

When I implement this, Bibledit does not allow me to make the footnote marker not have a space between it and the following word.

Want no space
      between FN marker and following word

If I remove the space after \ft, Bibledit "chokes" and presents it this way:

Bad Preview
        when there is no space between FN marker and following word

My questions:

(1) Is Bibledit functioning as it should? I.e., could this be changed in Bibledit and not mess anything up in future use of the USFM Bible text if there are no spaces between the FN markers and the following word?

(2) If this could be changed in Bibledit, should I file an issue for an enhancement in the future at https://github.com/bibledit/cloud/issues?

Thank you very much!
Eric


On 3/20/22 19:14, Robert Hunt wrote:

Teus Benschop

unread,
Mar 26, 2022, 1:09:34 PMMar 26
to bibledit...@googlegroups.com
Hello Eric,

I tried the spacing you desire to have in simple USFM.

\v 1 Now in the first year of Cyrus king of Persia, that Yahweh’s \f + \fr 1:1 \ft “Yahweh” is God’s proper Name, sometimes rendered “LORD” (all caps) in other translations.\f*word by Jeremiah’s mouth might be accomplished, Yahweh stirred up the spirit of Cyrus king of Persia, so that he made a proclamation throughout all his kingdom, and put it also in writing, saying,

This footnote has a space before the footnote caller, and so the footnote is attached to the next word, rather than to the previous word.

It looks like this in the verse editor.

1 Now in the first year of Cyrus king of Persia, that Yahweh’s 1word by Jeremiah’s mouth might be accomplished, Yahweh stirred up the spirit of Cyrus king of Persia, so that he made a proclamation throughout all his kingdom, and put it also in writing, saying,

 

1 + 1:1 “Yahweh” is God’s proper Name, sometimes rendered “LORD” (all caps) in other translations.


The USFM in your email is not well-formed.

It uses \add within a footnote, yet, this is not specified in the USFM standard at https://ubsicap.github.io/usfm/

If you "remove the space after \ft", then the \ft is no longer USFM, because if it were USFM, then it needs that space after \ft, like so: "\ft ".
Somehow Bibledit is not recognizing the "\ft" without the space, and so behaves in an undefined manner.

Met vriendelijke groeten,


Michael Johnson

unread,
Mar 26, 2022, 1:35:34 PMMar 26
to bibledit...@googlegroups.com
Hello, Eric.

Bibledit and USFM allow you to put footnote markers before the word or phrase, with no problem. You can control the spacing exactly how you want it to be. You just can't do it in the way you thought it should work. All STARTING USFM markers include the space after the marker as part of the markup, not as part of the text. That means that the space after the "\ft" is NOT in the text. It just looks like it in the raw USFM, but it isn't there in the ultimate output. If you remove that space, then the marker becomes extended to include whatever follows it. For example "\ft word" is the marker "\ft " followed immediately by "word". The text does not include a space, in that short example. If you type "\ftword", then you are trying to get the software (Bibledit, Haiola, Paratext, etc.) to recognize a new marker that doesn't actually exist, and you have removed "word" from the text of the footnote.

Now spaces AFTER an END marker in USFM (those that end in "*") are NOT part of the markup, but part of the text. So "\f*word" is the marker "\f*" followed by "word" and there is no space between the footnote marker and the word "word". That is OK. That is what you really wanted to do, and what you need to do to get the spaces to disappear that you don't want.

See https://ubsicap.github.io/usfm/about/syntax.html for details on how spaces are handled.

Does that make sense? I know USFM is a little confusing, because it was kind of made up incrementally over a period of many years, with each change being made so that it didn't break markup in existing texts. However, once you get used to it, it is pretty simple.

Another addition to USFM was the ability to nest text styles. That used to be forbidden. See the USFM documentation for details about the mysterious "+" notation (which is mostly mysterious because "\ft " counts as a text style in which other styles may be nested, like \+add ...\+add*.

Eric Chapman

unread,
Mar 26, 2022, 2:47:56 PMMar 26
to Teus Benschop

Thank you, Teus, for your help. I now see that my problem was the space I had after the \f* marker. I had it this way:

\f* \wj „Kas man ir tau
\f* \wj moterie?
It should have been this way:
\f*\wj „Kas man ir tau
\f*\wj moterie?
(1) But I still have a nagging problem: If I want to comply with USFM, am I really forbidden to use \add in footnotes? I thought with the + symbol it would be OK since it's nesting within the text (character) style \f.

(2) And what are the ramifications if I go ahead and use \+add … \+add* in footnotes (if that's forbidden)? I guess we can just strip them out sometime in the future if some program doesn't like them, right?

Thank you for your time!
Eric

Eric Chapman

unread,
Mar 26, 2022, 2:52:20 PMMar 26
to Teus Benschop

Hi, Michael,

Great help! You finally got it through my head to watch out for needed and unneeded spaces! As you'll see in my reply to Teus, I see the problem now. Since I want footnote markers before the text they refer to, I have to watch those spaces.

I had it this way:

\f* \wj „Kas man ir tau
\f* \wj moterie?
It should have been this way:
\f*\wj „Kas man ir tau
\f*\wj moterie?

You can also chime in on my question to Teus about \+add in footnotes, if you think it would be helpful. I cannot imagine footnotes without italics if they are referring to text that has \add in it.

BTW, I left the \add in the footnotes in that verse, and the are presented correctly in Bibledit's preview.

Thanks for help!

Eric

Teus Benschop

unread,
Mar 26, 2022, 3:33:05 PMMar 26
to bibledit...@googlegroups.com
Hello Eric,

> (1) But I still have a nagging problem: If I want to comply with USFM, am I really forbidden to use \add in footnotes? I thought with the + symbol it would be OK since it's nesting within the text (character) style \f.

My initial thoughts when discussing this issue was that the \add is not specified to be used in footnotes but it is specified to be used in a paragraph. See https://ubsicap.github.io/usfm/characters/index.html. Naturally added text can only be added in canonical text. But footnotes are not canonical by nature.
But on second thoughts, if you indeed quote canonical text with added content, then this could be in a footnote too.
Another thought is that in https://ubsicap.github.io/usfm/notes_basic/fnotes.html the "footnote content" markers are specified. One might conclude that the \add is not specified there, so is it allowed within footnotes?
Guess best would be to refer these questions to the USFM experts, which I don't claim to be.


> (2) And what are the ramifications if I go ahead and use \+add … \+add* in footnotes (if that's forbidden)? I guess we can just strip them out sometime in the future if some program doesn't like them, right?

Well, since Bibledit renders the \add and \+add well in footnotes, I'd guess there's no problem adding them. 
After all the aim is not to stick to strict standards, but the aim would be to get your Bible translated, right?
Again I'm sure others can discuss such issues better than I can.

Met vriendelijke groeten,

Michael Johnson

unread,
Mar 26, 2022, 5:29:39 PMMar 26
to bibledit...@googlegroups.com
Hello, Eric & Teus.

Yes, it is OK to use \+add ...\+add* in footnotes when appropriate (i.e. quoting a part of the canonical text that has \add ...\add* markers in it. This is not well documented at https://ubsicap.github.io/usfm/, unfortunately, but it is clearly allowed by not only Bibledit, but also by Paratext, Haiola, and probably other software as well. So are other character-level markups that are not specific to footnotes, such as \+tl ...\+tl*.

At the risk of giving too much information, there is an even stranger thing that is allowed, in that \xt ...\xt* is allowed outside of cross reference notes. I don't recommend doing that, but some translators do that thinking that it will make turning passage references into hot links possible. (In fact, in Paratext, it does do that, but most other software doesn't behave any differently with or without oddly-placed \xt ...\xt* markers.)
Reply all
Reply to author
Forward
0 new messages