search

bible-technology / scripture-burrito

Scripture Burrito Schema & Docs 🌯
http://docs.burrito.bible/
MIT License
21 stars 14 forks source link

int abbreviation not intuitive #65

Closed RobH123 closed 5 years ago

RobH123 commented 5 years ago

In The Ingredients Section https://docs.burrito.bible/en/v0.1.0-beta/metadata_ingredients.html, the snippet shows intnt and intMat. I was totally puzzled as to what these integers or internal versions were until getting to the last line on the page where I discovered it means introduction.

If it was changed to intront and introMat it would be so much more intuitive.

mvahowe commented 5 years ago

@RobH123 That's a fair point. The peripheral names in Scripture Burrito are derived from USFM3:

https://ubsicap.github.io/usfm/usfm3.0/peripherals/index.html

Personally, I think it would be confusing for SB to introduce small but significant deviations from USFM. (We did include intMAT etc to handle book introductions which, in USFM, tend to be prepended to the canonical text.)

klassenjm commented 5 years ago

The 'int' form is taken from the INT book ID in a (yes, Paratext) scripture project, and has been in use for many years. I don't think we want to revisit the identifiers documented in USFM 3 at this point. That would be somewhat more painful than a quick look at the reference for what int means. Hopefully 'int' will become more acceptable / natural with a bit of use?

da1nerd commented 5 years ago

Explaining what 'int' means sooner in the documentation could be helpful. I was also stumped for a bit.