search

ubsicap / usfm

Unified Standard Format Markers
39 stars 18 forks source link

Clean up and/or clarify quotes usage #117

Open jameschensmith opened 3 years ago

jameschensmith commented 3 years ago

I've noticed an inconsistency of quotes throughout the documentation, and was thinking there could be better direction on this. Below are two examples of the current usage.

From the usage throughout the documentation, it appears that the possible stance taken is that curved quotes are used for the USFM blocks, while straight quotes are used anywhere else. In this case, one of the action items could be to address the quotes which don't match this stance. Another action item may be to have a concise paragraph at the beginning of the documentation which talks about the usage inside USFM blocks. Maybe smart quotes could even be left to the USFM processor which implements the standard? Open to your thoughts :slightly_smiling_face:

Lastly, I wanted to take this opportunity to say that I'm interested in helping contribute to this standard. I can absolutely address the action items which come out of this issue. I also want to know how I can better get plugged in with the maintainers, whichever communication platform you may use :blush: Thank you!

klassenjm commented 3 years ago

@jameschensmith Thank you for finding and pointing to some inconsistencies here. This is helpful. The documentation will need to be reviewed and updated to be consistent and a note added to the Syntax Notes section.

Regarding your offer of help -- thank you. There is a current need to renew a working group around further development of USFM. I'll keep this record of your interest.

jameschensmith commented 3 years ago

@jameschensmith Thank you for finding and pointing to some inconsistencies here. This is helpful. The documentation will need to be reviewed and updated to be consistent and a note added to the Syntax Notes section.

I could address this in the documentation, but I would need confirmation on the stance taken regarding quotes usage.

  1. Outside of USFM code blocks, quotes could be formatted to straight quotes.
  2. Inside USFM code blocks, quotes could also be formatted to straight quotes. This would include a note in the syntax notes section explaining that smart quotes should be left to the USFM processor.
  3. Inside USFM code blocks, quotes could be formatted to curved quotes. This would include a note in the syntax notes section, explaining that quote formatting is left to the author of the USFM document.

I'm thinking either options 1 & 2 or 1 & 3. If you have another option, you could suggest that as well. Once there's a decision on the desired route to take, I could start on a PR for this change. :slightly_smiling_face:

Regarding your offer of help -- thank you. There is a current need to renew a working group around further development of USFM. I'll keep this record of your interest.

Looking forward to hearing back about this! :blush: