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
| Text | Common use |
|---|---|
Exercises (value of questions, answers, proposals) | gaps, affixes, clues, alternatives |
| Instructions and titles | a word quoted in another language: {lang=pt-PT§ser} |
Vocabulary words (text) | accepted spellings: colour|color |
translation_context | one context per language: {lang=en§vehicle}{lang=pt§veículo} |
Patterns (prefix, suffix) | forced pronunciation: ipa=ˈsʌmθɪŋ§ sth |
Five special characters
| Character | Role |
|---|---|
{ } | 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.
| Written | Accepted answers |
|---|---|
colour|color | colour, color |
I'd like {a flat|an apartment} | I'd like a flat, I'd like an apartment |
{the |}cinema | the 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é}.
| Attribute | Effect |
|---|---|
?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 | |
|---|---|
| Question | Yesterday 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.
- Only the keys
lang,section,input,type,ipaandrefexist; any other (lnag=,part=1) is ignored and the text loses its structure. typeonly accepts known values (affix,clue,context…); others are ignored.- Case matters:
lang=fr-FR, notLANG=FR-fr.
After an import, do a few exercises in the app: it is the best check.
Cheat sheet
| Written | Meaning |
|---|---|
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=…§text | forced pronunciation |
`{, `|, `§, `` | literal special character |