Unlocked Grammar Information

This site contains the official documentation for Door43’s Unlocked Grammar formatting information.

Contents:

Purpose

Purpose of this documentation

The purpose of this documentation is to present to the UGG, UHG, UAG, and UGC writers and editors the philosophy and the structure of the Unlocked Grammmar projects. This document also is meant to describe all the working procedures and management structure in the Unlocked Grammar projects. Finally, it will present the personnel with the needed information about online repositories and file locations, as well as instructions for working with them.

Purpose of the Unlocked Grammar projects

The Unlocked Grammmar projects are meant to provide in Christian resource-deprived languages a set of biblical language grammar resources similar to the resources that Western Christian scholars use. The Unlocked Grammar resources are intended initially to serve as brief references for the native translator’s rapid comprehension of the grammar in the original languages of the biblical text. Beyond this initial purpose, as the Unlocked Grammar resources are enhanced and expanded, they may be used as teaching grammars.

The grammars are intended to be translated and adapted into other languages, specifically the Gateway Languages.

Conventions

Examples

When we provide examples in an article we need to use the format below. Put the reference on its own line and then use a table that shows these four components:

  • the source text (Greek, Hebrew, or Aramaic)
  • the SBL style transliteration
  • the literal/interlinear translation
  • the smooth translation

See the following example:

Scripture Reference

Hebrew/Greek/Aramaic
transliteration
literal translation
smooth translation

See the Open Siddur transliteration page for help with Hebrew transliterations. You may also find the http://transliterate.com/ site helpful for both Hebrew and Greek translations.

Where possible, use the ULB for the smooth translation field.

Spelling

  • Shewa/sheva/shwa/shva should be spelled “shewa”
  • Use the full name of various terms instead of abbreviations (e.g. write “infinitive construct” rather than “inf. cs.”)

Structural

  • Do not duplicate the glossary entry in the article entry
  • For the UHG and UAG, paradigms/charts should go in a folder named after what the chart displays. For example, a chart of the demonstrative pronouns could go in content/chart_demonstrative_pronouns/01.md. For the UGG, at least initially, paradigms/charts will be placed in the content/paradigms folder with the name of the paradigm/chart that is displayed.

Typographical

  • Wherever possible, use the actual Hebrew, Aramaic, and Greek letters (whether vowels or consonants). If needed, you may put the name of the letter in parenthesis afterward.
  • Wherever possible, include vowels in Hebrew examples that are shown. Use the 3ms form of verbs to refer to the root or head entry of the verb.

Encoding

  • If you are using the web editor then you don’t have to worry about font encoding, the editor will automatically make it unicode.
  • If you are writing locally then you must ensure that you are using unicode.
  • The font doesn’t matter at this point as display will be taken care of in the rendered output formats (PDF, translationCore, etc.).

Bible References

Since we are writing especially for translators, we’ll use the USFM book codes for references. As an example, use “GEN 3:10” as the reference for Genesis 3:10.

Use the standard English versification system (which is from the KJV) for referring to Scripture. If there is a variance with the original language versification system, provide that reference in parenthensis. For example, “MIC 5:1 (MIC 4:14 in Hebrew)”.

Working with Door43 Git Service

Forking the repository

Before you begin working on creating or modifying files in one of the the Unlocked Grammar repositories, you will need to fork the project’s repository.

  1. Sign in to your Door43 account at https://git.door43.org/.
  2. Click Fork near the upper right-hand corner of the site.
_images/fork.PNG
  1. In the New Fork Repository window, keep the default Repository Name and Description and click on the Fork Repository button.

Note

Once you have forked the repository, you will need to work from the files on your fork only. Once you have committed changes to a file on your fork and are ready to merge those those changes to the Master repo, you will need to create a Pull Request.

Assigning yourself to issues

We will be tracking progress for the Unlocked Grammar projects using Issues on the repo.

  1. On the master repository site, click on Issues to see open issues.
  2. Click on an unassigned issue that is marked for the current sprint.
  3. Click on Assignee to the right of the issue description and select your username.
  4. Click on Labels to add the blue “In Progress” label to that issue once you begin work on it.

Creating a Pull Request

When you have completed work on a file and are ready for it to be reviewed and merged to the master repository, you will need to create a Pull Request that will be reviewed by another team member before being merged to the master repo.

  1. On the master repository site, click on Pull Requests near the top of the page, then click on the New Pull Request button. The site will compare your fork with the master repository and show differences at the bottom of the page.
  2. Add a title and a description that explain the changes you want to merge to the master repository.
  3. Click Create Pull Request.

Merging a Pull Request

Pull requests will show up near the top of the main repository page.

  1. Click on Pull Requests to see what needs to be reviewed and then merged with the master repository.

Note

Only review and merge content from another contributor, not your own content.

  1. View the file to review the content.
  2. If the content is accurate, merge the Pull Request with the master repository.

Closing Issues

After your Pull Request for an issue has been reviewed and merged into the master repository, you can mark your issue closed and remove the “In Progress” label from the issue.

Using Markdown

Markdown is the text formatting that the Unlocked Grammar projects use. The project sites include a built-in Markdown editor and previewer so that in-depth knowledge of the format is typically not necessary. However, there are a few exceptions when knowledge of Markdown format is helpful or necessary.

Line Breaks

If you want text to show up on separate lines then you need 2 line breaks between the lines. For example:

this will be on the same line

Shows up as

this will be on the same line

But the following will show up on separate lines:

this will be on

separate lines

Like this:

this will be on

separate lines

Tables

Since Markdown does not natively support all of the features required, such as row and column spans, tables required for the Unlocked Grammar declension and other paradigms/charts need to be created in HTML format. If you are not familiar with HTML, the easiest way to generate the HTML for these tables is to copy and paste the text into an HTML table generator.

Note

Charts are needed for many paradigms and declensions. These should be taken from public domain grammars to avoid copyright issues. For Greek, Nunn and Moulton are two public domain grammars that can be used. To save time, copy paradigms/charts from an electronic source rather than hand typing them. Some are probably on the Internet free (e.g., at archive.org) perhaps even in HTML format. However, some of those will need to be modified since older grammars tend to list ‘thou’ and ‘ye’ to differentiate 2nd person sg. & pl. and those should be ‘you’ or ‘you (sg.)’ and ‘you (pl.). Also, the terminology and abbreviations need to be consistent in all charts so that means some of the public domain charts will need to be modified.

To use the HTML table generator in Markdown files:

  1. Copy and paste your text into the formatted table view.

Note

Each paradigm table or chart should be complete with row and column headers, accents, vowels, and the English translation/equivalent for each cell.

  1. Check the box for “Do not generate CSS”.
  2. Click the Generate button.
  3. Copy the resulting HTML code.
  4. Click the Edit button for the appropriate Markdown file where the HTML table code belongs.
  5. Paste the HTML code into the Markdown file.
  6. Preview the file to make sure formatting is correct.
  7. If the chart or paradigm is complete, click the Commit Changes button to save the file changes to your fork.

Vocabulary

Since we are writing for a non-technical and non-native English reader we need to take great care in using technical terms. In short, if you can use a non-technical word and communicate the same thing as a technical word, please do. Only use technical jargon if it is required to communicate the point of the sentence.

The following lists are words that we suggest or disallow for use in order to help our resource communicate effectively.

Preferred Words

  • example

Disallowed Words

  • example

Writing for English Language Learners (ELL) and Translation

Grammatical Tips

  1. Do not use slashes
  2. Avoid complex sentence structure; use short sentences
  3. Keep subject, verb, and object close together
  4. Place main idea before exceptions and conditions
  5. Put general statements before specific statements
  6. Have only topic per paragraph
  7. Avoid the passive voice
  8. Relativizing can create issues for translators
  9. Some languages do not use non-restrictive relative clauses (RC). Readers may mistake them for restrictive RCs
  10. Some languages do not relativize the indirect object or the possessor. Inexperienced translators may have difficulty translating them
  11. Use the simple past, present, and future
  12. Be careful about using time and direction. Languages often related time to a direction, but they do not all use the same directions as English to indicate the movement of time
  13. Avoid using the present as a metaphor for the past
  14. Avoid nested statements, questions, and propositions
  15. Put alternative concepts into separate clauses or sentences
  16. Make logical relationships in sentences and paragraphs explicit
  17. Make headings (e.g., “Overview”) precise
  18. Try to make the first clause in the paragraph present the paragraph’s theme
  19. Ensure that each paragraph builds, instead of growing weaker or confused
  20. Delineate points that succeed each other: (first, second, third–or through other means)

Vocabulary Tips

  1. Avoid Slang
  2. Avoid jargon or overly technical language (not found in Scripture)
  3. Use simple vocabulary when possible
  4. Avoid compound/phrasal verbs
  5. Use direct language that is straightforward and to the point
  6. Try to avoid abstract language/nominalizing verb
  7. Try to avoid semantically complex expressions. This includes technical theological terms whenever possible.
  8. Use extra care when using loan words. These are words either borrowed by the NT from the LXX or borrowed by English from the NT Greek. This type of terminology will likely be unavoidable. Elaboration may be needed when dealing with loan words. Remember, these English words do not exactly correspond with the Greek concepts.
  9. Avoid metaphors, metonyms, and synecdoches

Spelling/Procedural

  1. Do not capitalize divine personal pronouns or attributes
  2. Do not use contractions
  3. Write in the third person
  4. In general, write in the past tense when describing events that have already occurred

5. Be cautious about tense in prophecy as this will have implications about whether a prophecy has been or will be fulfilled 6 If possible, juxtapose two ideas right next to each other. The example above could be written as two paragraphs starting with “Some scholars” and “Other scholars” or as two sentences in the same paragraph. 7. Avoid words with different possibly senses being used in a given paragraph. Also, make certain that a pronoun’s antecedent is clear and unmistakable. 8. If possible, avoid words with multiple abstract senses

Editorial

  1. Ensure that the paragraphs are well formed before diving into the trans friendly challenges for each sentence.
  2. Figure out what the author wants to say, rather than just look at what he has written.
  3. Make headings (e.g., “Overview”) precise. (See below)
  4. Watch out for unfortunate implications not intended by the author.
  5. Prefer shorter rather than longer sentences.
  6. Be ready to split a paragraph up into more than one paragraphs.