List File Syntax

Cerebware list files resemble dictionaries, with one entry per line. Each line consists of a foreign word to be learned, followed by a colon and then the English equivalent(s). Multiple English definitions can be separated by semicolons:
der Hund : the dog
der Mann : the man ; the husband

For most users, the syntax of these two examples covers 90% of vocab entries. At some stage, however, most users will want to add prompts in square brackets, to resolve ambiguities. Advanced users might also want to add pictures, audio, or mnemonics, or indicate that an item should only be tested in a particular direction, or only via multichoice. This Help file explains how to indicate such preferences and additions via a list file. Note that adding advanced content can also be done via the Edit Dialog, which is initially easier - no syntax is needed. The main advantage of doing it via a list file is that the resulting list can then be shared with others. Also, once the syntax is understood, teachers creating lists will find it much quicker to type lists into a word processor, cutting and pasting the tags as needed, rather than to edit the items individually through the graphical interface.

If some of the syntax described in this Help file seems complicated, just remember that help is always available through typing shortcuts. We recommend that you edit your lists within the Cerebware Text Editor. Choose 'Text... New... New Plain Text File' to switch the program to Text Editor mode. The upper window of the Trainer, which is usually where the history of your activities appears, converts to a simple text editor. When typed in this main editor window:

  1. {?} expands to the set of tags that belong in curly braces,
  2. (?) expands to tags that belong in parentheses,
  3. [?] expands to tags that belong in square brackets, and
  4. |?| expands to a full listing of all possible tags.

Prompts

Prompts can appear on the 'foreign' side of the colon (side A of the flashcard), or the 'English' side (side B). Don't get the sides confused. The prompt on the foreign side appears with the foreign item but it describes the English item. Similarly, the prompt on the English side describes the foreign word.
sie [singular] : she
sie [plural] : they
Sie : you [formal]
du : you [singular, familiar]
das Skelet : the skeleton [Starts with S]
das Gerippe : the skeleton [Starts with G]

Tags in Curly Braces

Curly braces are used for audio tags, sentence tags, and grammar/footnote tags. If you type {?} in the main Cerebware window, it expands to reveal the four possible 'curly' tags: {contextual audio | sentence tag | footnote | pronunciation}. The tags are separated by a vertical bar '|' and the position of each tag (1st, 2nd, 3rd, 4th) indicates what sort of tag it is.

The first and fourth tags refer to audio files - the files should have the suffix '.au', and be in Java audio format, or '.mp3', and be in MP3 format. The files should reside in the audio subfolder of the Vocab Trainer folder. The tags should simply consist of the file name (without the full path). As explained in 'Setting up audio', there are two types of audio that can be associated with each vocab item. If the audio tag appears alone or as the first tag in curly braces, it is interpreted as contextual audio. If it is the fourth field (including blank fields), it indicates pronunciation audio.
die Geschichte : the story {HPSW1.3.au}
die Geschichte : the story { HPSW1.3.au | | | Geschichte.au}

Missing fields can be left blank, or filled with spaces. If the only field of interest is the pronunciation field, for instance, then the first three empty fields must be represented by vertical lines: die Geschichte : the story { | | | Geschichte.au }

The second field within braces is reserved for sentence tags, and normally matches the first field, but minus the '.au' or '.mp3' file suffix. It consists of a chapter name ('HPSW1' in this example) and a sentence number ('3'). See 'Linking to a book chapter' for more details.
die Geschichte : the story {HPSW1.3.au | HPSW1.3}

The third field is reserved for 'footnotes'. These are explanatory text or HTML files that are loaded when the vocab item first appears. The text/HTML files can include explanations of where the item came from, hints about its pronunciation or usage, comments on the structure of the containing sentence, or grammar principles that should be reviewed before proceeding. The footnote tag should not include a file suffix. For instance, to load the file 'GermanGrammar\The Dative Case.html', the tag should just contain 'The Dative Case'. When the item appears, the Cerebware program will look for an HTML file or standard text file corresponding to the name of the footnote, searching the Themes and Grammar folders of the relevant language, and displaying the first matching file it finds. For instance, the following line tells the Cerebware program to load and display the introductory file 'GermanGrammar\Harry Potter Glossary.html' when the first word of the glossary is encountered:
ein : a { | HPSW1.1 | Harry Potter Glossary }

The footnote can also be used as a category/theme marker by adding footnote tags to the first and last items in the theme. (See 'Using the Edit Dialog'.) The footnote tag for the first item should match the theme name, and the last item should be tagged with 'END'. Note the two vertical lines.
der Hund : the dog {|| Animals |}
... more items ...
die Katze : the cat {||END}

Footnotes can also link to online content, making it easy to build up a virtual textbook of useful links. Here is what a link to a Spanish article about suffixes might look like:
el hombrecillo : the small man { |LSDVP1.53 | ^http://www.press.uchicago.edu/Misc/Chicago/spanishdictionary/suffixes.html }

Note that the address appears exactly as it would in your browser, complete with an 'html' suffix. This does not mean that the 'html' suffix should be added to regular grammar tags, such as 'Pronouns'.

To avoid seeing the long web address during actual use of the flashcard, enter a synonym such as "Suffixes", in quotation marks, before or after the web address.
el hombrecillo : the small man3 { |LSDVP1.53 | ^"Suffixes" http://www.press.uchicago.edu/Misc/Chicago/spanishdictionary/suffixes.html }
el hombrecillo : the small man4 { |LSDVP1.53 | ^ http://www.press.uchicago.edu/Misc/Chicago/spanishdictionary/suffixes.html "More suffixes"}

During normal testing, the linked web page does not load automatically (which might be annoying), but it can be reached with a single click of the 'Grammar &' button, which goes purple to indicate that linked content is available. Clicking the button launches your default browser to show the page. When typing or pasting the address, it becomes a live hyperlink as soon as you add a space at the end. Ctrl-click the link to test it straight from the Text editor.

(A similar syntax can be used to add bookmarks to the Grammar menu. Click 'Edit Topics' under the Grammar menu, and add a line for each bookmark like this: "Suffixes" http://www.press.uchicago.edu/Misc/Chicago/spanishdictionary/suffixes.html )

In summary, the grammar tag can contain any of the following:

Tags in Round Parentheses

Typing (?) in the main Edit Window expands to (main image | mnemonic image | mnemonic text).

The image tags should refer to image files that reside in the images subfolder. Supported formats include GIF and JPG files. The tags should include the appropriate file suffix (such as 'cat.gif'), but the full path name is not required for files in the images folder. Online images can be referenced with their full address, 'http:\\... etc'. Further details on use of the images can be found in 'Using the Edit Dialog'.

The mnemonic text differs from the other 'round' tags in that it does not refer to a file name but contains the actual mnemonic text. Most users will add their own mnemonics as needed, via the Edit Dialog, so this field can usually be left out.

Missing fields must be represented as blank spaces. For instance, the mnemonic text always appears after two vertical bars, within round brackets, so if one or more pictures is missing then it may appear as follows:
foreign phrase : English phrase ( | mnemonic.gif | mnemonic text)
foreign phrase : English phrase ( | | mnemonic text)

The ^Upload Tag

The up-pointing caret, ^, is used to indicate a special use of the footnote tag. Usually, a footnote tag serves a dual purpose: it marks a category and triggers display of a file. For instance, here is a sample of a grammar lesson in Spanish:
el <= the [masculine singular] {||Definite articles}
la <= the [feminine singular]
lo <= the [neuter]
los <= the [masculine plural]
las <= the [feminine plural] {||END}

Cerebware uses the tag 'Definite articles' to mark this group of items as a single lesson accessible from the Grammar menu. It also displays a file (uploads it from disk to screen), 'Definite articles.html', when the first item of the lesson is encountered. What if the designer of the lesson wants to display another file, 'Uses of lo.html', when 'lo' is reached, but still wants these five items to stay within the same lesson? Adding a new footnote tag to 'lo' would normally create a new category running from 'lo' to the 'END' tag. To suppress this, and to upload the file without changing categories, add a tag prefixed with the upload symbol:
el <= the [masculine singular] {||Definite articles}
la <= the [feminine singular]
lo <= the [neuter]{||^Uses of lo}
los <= the [masculine plural]
las <= the [feminine plural] {||END}

Additional Tags

The following symbols also have special meaning within list files:
  1. & - Marks an item as multi-choice only.
  2. @ - Marks an item as not suitable for multi-choice.
  3. $ - Marks an item with an image as suitable for text-free testing.
  4. # - Within a prompt tag, indicates an alternative heading.
  5. || - Indicates learning dependencies.

Text-free testing

For simple nouns and verbs, it is often possible to find a picture that clearly indicates the meaning. Then, instead of translating from English into the target language, a student can simply provide the foreign word that matches the picture. This encourages the student to think in the target language. To suppress display of the English side of a flashcard, tick the 'suitable for text-free testing' in the Edit Dialog or, equivalently, add a dollar sign, '$' to the vocab item, like this:
die Katze : the cat (cat.gif) $

Alternative headings

The use of alternative headings is discussed in 'Using the Edit Dialog'. They are useful in languages with complex scripts, where the default headings (the name of the target language on one side and 'English' on the other) are not adequate. For instance, students of Japanese must learn the kanji symbols and also the pronunciation for each new vocabulary item. The pronunciation can be written in latin script (romaji), or the Japanese phonetic syllabry (hiragana). When faced with the English word 'dog', on one side of the flashcard, how does the student know what is expected on the other side? One way to do this would be with prompts:
inu : dog [pronunciation]
犬 : dog [kanji]

When these items appear in a test, the student will face a question of the form:
English: dog (kanji)
Japanese:

But what if the flashcard must test the kanji-pronunciation relationship and does not have an 'English' side? Standard prompts would cope with this poorly:
犬 [pronunciation] : inu [kanji]

This item, when testing in the forward direction, would look like this:
Japanese: 犬 (pronunciation)
English:

The desired answer, 'inu', is not actually English. A better question would look like this:
Kanji: 犬
Pronunciation:

The 'Pronunciation:' in the second line is an alternative heading (overriding the default 'English:', and it can be indicated within a prompt by use of the hash symbol.
犬 [#Pronunciation] : inu [#Kanji]

Note that the heading tag for the kanji side says 'Pronunciation', and the tag on the pronunciation side says 'Kanji'. This might seem back-to-front but makes sense if you consider that the flashcard must give clues about what is on the other side, and the alternative heading is a type of prompt. In fact, this example is very similar to the earlier one using standard prompts ( 犬 [pronunciation] : inu [kanji] ). The difference is that the prompt text is not merely displayed as a hint, in parentheses, but is promoted to become a heading, overriding the default 'English:' or 'Japanese:'. Normal prompt text can also be placed inside the square brackets, along with an alternative heading, but it must appear before the hash symbol:
犬 : dog [common form #Kanji]

Learning dependencies

Learning dependencies are explained in 'Using the Edit Dialog'. In essence, they are prerequisite items that must be known before the current item can be shown. For instance, a multiple-kanji word in Japanese could be held back until each of the component symbols had been learned, or the subjunctive form of a German verb could be held back until the regular form was known. In most languages, it makes sense to hold back the plural forms of nouns until the singular form is known. To indicate dependencies, place two vertical lines at the end of an item, and then list the dependencies. For instance, the following text creates two flashcards and indicates that the kanji for 'dog' should not be displayed until the pronunciation is known:
inu : dog [#Pronunciation]
犬 : dog [#kanji] || inu

Multiple dependencies can be separated by vertical lines. The following line means, do not test this item until both 'dog' and 'inu' are known - it will only be shown when at least one item bearing 'dog' is known, and at least one bearing 'inu' is known. These do not have to be on the same card. The suggestion to hold a card back may be overridden if the Trainer does not have enough spare cards.
犬 : dog [#kanji] || inu | dog

Comments

Unlike prompts and most of the other tags described here, comments are not an integral part of the word list, and can be safely ignored by most users. When extracting words from a block of foreign text, however, warnings will be added to the text file to indicate potential duplications, and these will appear as comments in angled brackets. If, for instance, a word appears capitalised and uncapitalised in a block of text, simply because it happens to have been at the start of a sentence in one place, but not another, it is important not to make two separate flashcards. Each of these words will thus carry a warning when first extracted. Users can also add their own comments or descriptions, including details of authorship, within any list file.

Warnings and other comments are separated from the definitions by < angled brackets > .

That's it!

Remember, you can get a full syntax summary at any time by typing |?|, which expands to:
< &MCQ @noMCQ $text-free > Foreign [prompt #alt Head B] : English [prompt #alt Head A] {contextual audio | sentence tag | footnote-plus-category-marker or ^footnote-without-category-marker | pronunciation} (main image | mnemonic image | mnemonic text) || dependency 1 | dependency 2 | etc |