Skip to content
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

Potential marker reformat for en_tn Chunk files #55

Open
destatez opened this issue Jul 26, 2017 · 9 comments
Open

Potential marker reformat for en_tn Chunk files #55

destatez opened this issue Jul 26, 2017 · 9 comments

Comments

@destatez
Copy link

Discussion within the tn Resource team has raised a proposal to change the marker structure within each Chunk file, not any of the intro.md files. The current documentation shows the actual Snippet lines as having a single # (hash) preceding the Snippet text. There is no documentation provided for the other "marker" lines in those files: "# translationWords", "# Connecting Statement:", or "# General Information:". These later 2 are really not Snippets. The proposal is to keep the "# translationWords", as-is, since it really is a sectional divider within the file and deserves first rank. The later two of the list above would be formatted with double # (hashes) as: "## Connecting Statement:" and "## General Information:" since they are both informational headers which should deserve 2nd rank. All of the remainder of marker lines are "really" snippets and should have 3 # (hashes) as in: "### We should not be like Cain" since they are the lead-ins to the data and deserve a third ranking. An example of this proposal is to 1jn\03\11.md:
1jn_03_11_Proposed.txt

@da1nerd
Copy link
Contributor

da1nerd commented Jul 27, 2017

@jag3773 do you want to weigh in on this as well?

I have one thought and one suggestion.

  1. @destatez what is the purpose of using different heading levels within the notes? Is that strictly for visual aesthetics or are you trying to impose some sort of order or hierarchy?
  2. We could support the proposed changes by slightly modifying the spec to state the headings could be of any level. Then applications that need to parse the notes into manageable pieces could still split on the headers. The applications could keep inferred hierarchy if they chose to.

As far as I know this would not negatively affect tN generation for either the v3 or v2 APIs. However, it would require some tweaks to the code to fully support it.

@richmahn
Copy link
Member

richmahn commented Jul 27, 2017

Here's my suggestion for readability and parsing programmatically after doing the tN PDFs (compare with https://git.door43.org/Door43/en_tn/raw/master/1pe/05/12.md). Better to make to clear what Bible text to include (my Bible link format is just made up but would be helpful to have something like we do for RC links, thus can inject scripture in one of the notes as well if wanted):

# 1 Peter 5:12-14

 ## UDB

[[bible://en/udb/1pe/05/12-14]]

## ULB

[[bible://en/ulb/1pe/05/12-14]]

## translationNotes

### I have written to you briefly through him

Silvanus wrote the words that Peter told him to write in the letter.

### what I have written is the true grace of God

"I have written about the true grace of God." Here the word "grace" refers to the gospel message, which tells of the kind things that God has done for believers. (See: [[rc://en/ta/man/translate/figs-metonymy]])

### Stand in it

The word "it" refers to "the true grace of God." Being strongly committed to this grace is spoken of as standing firmly in one place, refusing to move. AT: "Remain strongly committed to it" (See: [[rc://en/ta/man/translate/figs-metaphor]])

### The woman who is in Babylon

Here "The woman" probably refers to the group of believers who live in "Babylon." Possible meanings for "Babylon" are 1) it is a symbol for the city of Rome, 2) it is a symbol for anywhere that Christians are suffering, or 3) it refers literally to the city of Babylon. It most likely refers to the city of Rome. (See: [[rc://en/ta/man/translate/writing-symlanguage]])

### who is chosen together with you

This can be stated in active form. AT: "whom God has chosen as he has chosen you" (See: [[rc://en/ta/man/translate/figs-activepassive]])

### my son

Peter speaks of Mark as if he is his spiritual son. AT: "my spiritual son" or "who is like a son to me" (See: [[rc://en/ta/man/translate/figs-metaphor]])

### a kiss of love

"a loving kiss" or "a kiss to show your love for each other"

## translationWords

* [[rc://en/tw/dict/bible/other/silas]]
* [[rc://en/tw/dict/bible/kt/faithful]]
* [[rc://en/tw/dict/bible/kt/brother]]
* [[rc://en/tw/dict/bible/kt/exhort]]
* [[rc://en/tw/dict/bible/kt/testimony]]
* [[rc://en/tw/dict/bible/kt/true]]
* [[rc://en/tw/dict/bible/other/babylon]]
* [[rc://en/tw/dict/bible/kt/elect]]
* [[rc://en/tw/dict/bible/other/johnmark]]
* [[rc://en/tw/dict/bible/kt/son]]
* [[rc://en/tw/dict/bible/other/kiss]]
* [[rc://en/tw/dict/bible/kt/love]]
* [[rc://en/tw/dict/bible/other/peace]]
* [[rc://en/tw/dict/bible/kt/inchrist]]

@richmahn
Copy link
Member

@neutrinog : the multi-levels helps in generating the final files (HTML and PDF) you can see as the progress from compiled MD to HTML to PDF here: https://api.unfoldingword.org/test/tn8-full/ (note, my Bible links are a little different, just for internal use as I inject the Bible verses at the HTML stage but note what to inject at the compiled MD level)

@jag3773 jag3773 changed the title Potential marker reformat for en_tn Chuck files Potential marker reformat for en_tn Chunk files Jul 27, 2017
@da1nerd
Copy link
Contributor

da1nerd commented Jul 27, 2017

@richmahn this whole section is redundant as far as data goes because it is inferred by the structure of tN.

# 1 Peter 5:12-14

 ## UDB

[[bible://en/udb/1pe/05/12-14]]

## ULB

[[bible://en/ulb/1pe/05/12-14]]

## translationNotes

If you just want to make things look pretty when generating content I would suggest adding extra formatting and information at compile time. This reduces the content creation load and makes it easier for programs like tS to parse and display notes correctly.

not to mention the bible links above should have been formatted like [[rc://en/ulb/book/1pe/05/12-14]] etc.

@jag3773
Copy link
Contributor

jag3773 commented Jul 28, 2017

I'm thinking that it would be best to adopt approach like we're using for the ubn. Essentially we have one chapter per file and then we use hashtags in order to specify which verses are being referenced. The hashtags can also be used to specify certain types of comments, to categorize them.

If we go this route I would suggest not changing the current spec but rather adding a new type into which ubn, ubc, tn would all fit.

@jag3773
Copy link
Contributor

jag3773 commented Aug 25, 2017

@neutrinog As I read http://resource-container.readthedocs.io/en/latest/container_types.html#help-help it looks like a H1 heading is not required, it's just that the example only shows H1 headers. The page says, "When parsed by an app the helps in this chunk are split at the headers." I would see this as allowing multiple levels of headers, is that correct?

Second question @neutrinog , would making @destatez's suggested change require updates to tS?

@da1nerd
Copy link
Contributor

da1nerd commented Aug 25, 2017

@jag3773 that is correct. You can use any level or a mixture of levels for headings. With the current implementation each header would be treated as a separate clickable note in the app.

Using the example from @richmahn above:

  • # 1 Peter 5:12-14 would be empty
  • ## UDB would contain [[bible://en/udb/1pe/05/12-14]]
  • ## translationNotes would be empty
  • ### I have written to you briefly through him would contain Silvanus wrote the words that Peter told him to write in the letter.
  • ## translationWords would contain the list of word links.

etc.

@da1nerd
Copy link
Contributor

da1nerd commented Aug 25, 2017

After reviewing the code and the spec again I believe the example file uploaded by @destatez should work just fine without any changes to either code or spec.

From the code's perspective all it cares about is a header (of any size) followed by some text (anything not also a paragraph).

When it comes into the app you'll see links in the notes tab like:

  • Connecting Statement:
  • General Information:
  • We should not be like Cain
  • brother
  • Why did he kill him? Because [this because may be a typo in the example]
  • his works were evil and his brother's righteous
  • translationWords

@jag3773
Copy link
Contributor

jag3773 commented Aug 29, 2017

@destatez There are several other requirements that are currently being discussed that may significantly affect the structure of tN going forward. I like what you have proposed but would like to wait to implement it until some of these other requirements are defined first as we'll likely need synthesize several ideas together.

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

No branches or pull requests

4 participants