Footnotes, Formatting, and References

Currently the data structure for footnotes and formatting look like this:

type Verse struct {
    Number     int          `json:"number"`
    Text       string       `json:"text"`
    Footnotes  []Footnote   `json:"footnotes,omitempty"`  // optional
    Formatting []Formatting `json:"formatting,omitempty"` // optional
}

type Footnote struct {
    Marker string `json:"number"`
    Text   string `json:"text"`
    Start  int    `json:"start"`
    End    int    `json:"end"`
}

type FormattingType string

// define valid FormattingType values
const (
    FormatBold      FormattingType = "bold"
    FormatItalic    FormattingType = "italic"
    FormatUnderline FormattingType = "underline"
    FormatRedLetter FormattingType = "red-letter"
    FormatSmallCaps FormattingType = "small-caps"
)

type Formatting struct {
    Type  FormattingType `json:"type"`
    Start int            `json:"start"`
    End   int            `json:"end"`
}

For the sake of this, lets assume we are trying to store Romans 1:17 from the Legacy Standard Bible

Screenshot from https://www.biblegateway.com/passage/?search=Romans+1%3A17&version=LSB

In the current structure, the JSON would look something like this:

{
  "number": 17,
  "text": "For in it the righteousness of God is revealed from faith to faith; as it is written, \"But the righteous will live by faith.\"",
  "footnotes": [
     { 
       "marker": "a",
       "text": "Or _by_",
       "start": 31,
       "end": 35
       },
      { 
       "marker": "b",
       "text": "Or _But he who is righteous by faith shall live_",
       "start": 70,
       "end": 106
       }
  ],
  "formatting": [
    { 
       "type": "italic"
       "start": 10,
       "end": 13
       },
      { 
       "type": "small-caps",
       "start": 70,
       "end": 106
       }

  ]
}

I think my first suggested change would be to add a type to markers, (literal, alternative, commentary and maybe other) to denote the type of footnote it is, and then add another section for cross-references.

I am also open to alternative theories on how to denote which text in the string needs formatting or references applied to it. Currently start and end is the char count start and end inside the string.

Assuming we stick with the current method of denoting where the formats exist, I would not be against a few methods on the Verse struct that could help render out in HTML and Markdown the footnoting and formatting as much as is possible.

Obviously red-letters and small-caps are not a native markdown feature, so Im not sure how we handle that (but honestly whatever app consumes the text can choose to use our methods or not)

After playing with this, I've realized it would be substantially easier to store all formattable fields as a custom Markdown string.

The library will provide helpers to return plain text as well as HTML markup from the markdown stored in the fields.

Leaving these here so I can decide next time I pick it up:


type BibleMarkdown string

// Removes all formatting from the text and returns a string
func (b BibleMarkdown) Text() string {
    // TODO: implement
    return ""
}

// Returns the text in HTML format
func (b BibleMarkdown) HTML() string {
    // TODO: implement
    return ""
}

// -----

// Verse holds the number and text of a verse
type Verse struct {
    Number    int           `json:"number"`
    Text      BibleMarkdown `json:"text"`
    Footnotes []Footnote    `json:"footnotes,omitempty"` // optional
}

// Footnote holds the text and location of a footnote
type Footnote struct {
    Text  BibleMarkdown `json:"text"`
    Start int           `json:"start"`
    End   int           `json:"end"`
}

So the output would be similar to this. (I have yet to decide how small caps will be marked inline, but I used + for the example)

{
  "number": 17,
  "text": "For in it _the_ righteousness of God is revealed from faith to faith; as it is written, \"+But the righteous will live by faith.+\"",
  "footnotes": [
     { 
       "marker": "a",
       "text": "Or _by_",
       "start": 31,
       "end": 35
       },
      { 
       "marker": "b",
       "text": "Or _But he who is righteous by faith shall live_",
       "start": 70,
       "end": 106
       }
  ]
}

And then ...

PlainText() would return:

For in it the righteousness of God is revealed from faith to faith; as it is written, "But the righteous will live by faith."

ToHTML() would return:

For in it <i>the</i> righteousness of God is revealed from faith to faith; as it is written, "<span class="small-caps">But the righteous will live by faith.</span>"

solafide-dev / gobible

Footnotes, Formatting, and References #6