Super Parrot Documentation

Parrot Markup

Parrot Markup is the small syntax that enriches a dictionary's texts: the gaps of an exercise, the accepted answers, punctuation that is not marked, clues, words in another language, pronunciation. Plain text stays plain text: add markup only where it helps.

Where to use it

TextCommon use
Exercises (value of questions, answers, proposals)gaps, affixes, clues, alternatives
Instructions and titlesa word quoted in another language: {lang=pt-PT§ser}
Vocabulary words (text)accepted spellings: colour|color
translation_contextone context per language: {lang=en§vehicle}{lang=pt§veículo}
Patterns (prefix, suffix)forced pronunciation: ipa=ˈsʌmθɪŋ§ sth

Five special characters

CharacterRole
{ }enclose a group
|separates alternatives
§ends an attribute placed at the start of a text
`escapes the next character

Everything else, spaces included, is ordinary text.

Alternatives

| separates forms that are all accepted. Outside braces it covers the whole text; inside braces, only the part that varies.

WrittenAccepted answers
colour|colorcolour, color
I'd like {a flat|an apartment}I'd like a flat, I'd like an apartment
{the |}cinemathe cinema, cinema: an empty branch makes a word optional

In an exercises file, prefer one answer or proposal line per answer: the import joins them with | itself, and the spreadsheet stays readable.

Attributes

An attribute is written key=value§ at the start of a text, usually in a group: {lang=pt-PT§ser}. Several attributes follow one another, each ending with its own §, in any order: {type=clue§lang=fr-FR§passé} equals {lang=fr-FR§type=clue§passé}.

AttributeEffect
?1§ (or input=1§)a numbered gap
#1§ (or section=1§)a numbered section of the exercise
lang=…§the text's language: it is read by that language's voice
type=affix§an affix: shown, never marked
type=clue§a clue, shown in brackets
type=context§a context that removes an ambiguity
ipa=…§the forced pronunciation

An attribute only applies to the branch it precedes. {?1§was|were} means “was in gap 1, or were outside the gap”: were would be refused. For the gap to accept both, wrap the alternatives: {?1§{was|were}}.

Gaps

In the question, {?1§} marks the place to fill. In the answer, {?1§bought} gives what is expected in that gap. Several gaps are numbered ?1, ?2…

Written
QuestionYesterday I {?1§} a new phone.
Answer{?1§bought}
Two gaps{?1§buy}{?2§bought}

Only the content of the gap is marked: what surrounds it in the question is shown, not typed. In an exercises file, the index column sets the gap number, so an answer is often written with no markup at all.

Affixes: shown, never marked

{type=affix§…} wraps what goes with the answer without being part of it: final punctuation, Spanish opening punctuation, quotation marks. The learner does not type it and is never penalised.

{?1§A coffee, please}{type=affix§.}
{type=affix§¿}Cómo te llamas{type=affix§?}

The article and the to of the English infinitive are affixes too, but they are declared once and for all in a pattern (see Creating a dictionary).

Clues and context

{type=clue§…} adds a clue shown in brackets: the verb to conjugate, a register, the expected form. It is not typed. It is read aloud when the Speak the clues option is ticked (see Speech and voice).

Yesterday I {?1§}{type=clue§buy} a new phone.
{?1§How do you do}?{type=clue§formal}

{type=context§…} removes an ambiguity, like a vocabulary word's context: it is always read. A clue must never give away the answer.

Languages

{lang=…§…} flags a fragment written in a different language from the rest of the text: it is read by its own language's voice, with its accent. Give the full code, with the country.

Fill in with “{lang=pt-PT§ser}”.
{type=clue§{lang=pt-PT§você}, affirmative}

Sections

An exercise can have several numbered sections, for example the sentence to complete and, beside it, its translation to guide the learner. {#2§…} puts a text in section 2. In an exercises file, the section column of the _ line says which section holds the question and the answer.

{#1§I gave up.}{#2§lang=fr-FR§J'ai abandonné.}

Pronunciation

ipa=…§ forces the pronunciation of the text it precedes, in the International Phonetic Alphabet, when text-to-speech gets it wrong. It transcribes only that text, never the sentence around it.

{?1§ipa=ˈrɛd§{read}}
ipa=ˈsʌmθɪŋ§ sth

Writing a special character

The backtick makes the next character literal: `{, `}, `|, `§, and `` for the backtick itself. It is also used in CSV files, for a cell that starts with ~, + or - without being a command (`+18).

No error messages

Parrot Markup is never rejected: a brace too many or too few, an unknown attribute, nothing blocks the import. Convenient, but a typo goes unnoticed.

After an import, do a few exercises in the app: it is the best check.

Cheat sheet

WrittenMeaning
a|b, {a|b}alternatives
{word |}optional word
{?1§} / {?1§answer}gap in the question / expected answer
{?1§{a|b}}gap with several answers
{type=affix§.}shown, never marked
{type=clue§…}clue in brackets
{type=context§…}context that removes an ambiguity
{lang=pt-PT§…}fragment in another language
{#2§…}section 2
ipa=…§textforced pronunciation
`{, `|, `§, ``literal special character