<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN"
 "dtd/kdedbx45.dtd" [
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE"><!-- change language only here -->
]>

<book id="kwordquiz" lang="&language;">

<bookinfo>
<title>The &kwordquiz; Handbook</title>

<authorgroup>
<author>
<firstname>Peter</firstname>
<surname>Hedlund</surname>
<affiliation>
<address><email>peter.hedlund@kdemail.net</email></address>
</affiliation>
</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>


<copyright>
  <year>2003</year>
  <year>2004</year>
  <year>2005</year>
  <year>2008</year>
  <holder>Peter B. Hedlund</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>


<date>2023-07-04</date>
<releaseinfo>Applications 23.08</releaseinfo>

<abstract>
<para>
&kwordquiz; is a flashcard and vocabulary learning program by &kde;.
</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>kdeedu</keyword>
<keyword>KWordQuiz</keyword>
<keyword>flashcard</keyword>
<keyword>vocabulary</keyword>
<keyword>language</keyword>
<keyword>education</keyword>
<keyword>school</keyword>
<keyword>college</keyword>
<keyword>university</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
<title>Introduction</title>
<para>
&kwordquiz; is a tool that gives you a powerful way to master new vocabularies. It may be a language or any other kind of terminology.
</para>
<sect1 id="easy-to-use">
<title>Easy to use</title>

<para>
With &kwordquiz; you build your own vocabulary documents in a simple and intuitive way. The basic layout is a two-column spreadsheet where you type vocabulary entries in one form that you know and in another form that you want to learn. You change the titles of the columns to reflect what you are practicing.
</para>

<sect2 id="quiz-types">
<title>Quiz types</title>

<para>When you have entered your vocabulary, you are ready to start a quiz. Maybe you want to start with a flashcard session. Later you can move on to a multiple choice quiz, or do the powerful question and answer quiz. You get instant feedback on correct and incorrect answers, and you have the option to repeat any errors, further improving your learning efficiency. If you need a little extra help you can use the hint function.
</para>
</sect2>


<sect2 id="practice-modes">
<title>Practice modes</title>

<para>You can select how you want to practice. &kwordquiz; offers three different modes to make practicing more efficient. The different modes make it possible to decide which column is used as a question, answer or both. Additionally you can choose whether to use a sequential or random order.
</para>
</sect2>

<sect2 id="vocabulary-documents">
<title>Vocabulary documents</title>
<para>
&kwordquiz; can open several types of vocabulary data. The default format is <filename class="extension">.kvtml</filename>, a file format shared by several &kde; programs. &kwordquiz; should also open <filename class="extension">.wql</filename> files created by &kwordquiz; for &Windows;, <filename class="extension">.csv</filename> files with comma separated text, <ulink url="http://www.vokabeln.de/v1/download.htm"><filename class="extension">.voc</filename> files</ulink> created by the old version of Vokabeltrainer, <ulink url="https://sourceforge.net/projects/xdxf/files/dicts-XDXF/"><filename class="extension">.xdxf</filename> files</ulink>, and <filename class="extension">.xml.gz</filename> files created by the old versions of <ulink url="http://pauker.sourceforge.net">Pauker</ulink>.
</para>
<para>
&kwordquiz; can save your vocabulary documents in several different formats. The default is the <filename class="extension">.kvtml</filename> format used by other &kde; programs. Another available option is comma separated text <filename class="extension">.csv</filename>.
</para>
<para>
You can have several files open at the same time, and easily copy or move entries between files.
</para>
</sect2>
</sect1>
</chapter>

<chapter id="commands">
<title>Command Reference</title>
<sect1 id="mode-menu">
<title>The Options Menu</title>
<para>
The menu provides 3 different options for the quiz which are not mutually exclusive.</para>

  <note><para>The menu names will change to reflect the column titles of the currently active vocabulary document. The selected mode will apply to Flashcard, Multiple Choice and Question &amp; Answer.</para>
  </note>
<variablelist>

  <varlistentry>
    <term>
      <menuchoice>
        <guimenu>Options</guimenu>
        <guimenuitem>Shuffle</guimenuitem>
      </menuchoice>
    </term>
    <listitem>
      <para>
        During the quiz you will be given the entries in a random order, but each entry will be processed once.
      </para>
    </listitem>
  </varlistentry>


  <varlistentry>
    <term>
      <menuchoice>
        <guimenu>Options</guimenu>
        <guimenuitem>Column 1 -&gt; Column 2</guimenuitem>
      </menuchoice>
    </term>
    <listitem>
      <para>
        During the quiz you will be given the entries of Column 1 and asked to provide the corresponding Column 2 entries.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>
      <menuchoice>
        <guimenu>Mode</guimenu>
        <guimenuitem>Column 2 -&gt; Column 1</guimenuitem>
      </menuchoice>
    </term>
    <listitem>
      <para>
        During the quiz you will be given the entries of Column 2 and asked to provide the corresponding Column 1 entries.
      </para>
    </listitem>
  </varlistentry>
</variablelist>
</sect1>
</chapter>

<chapter id="welcome-page">
<title>The Welcome Page</title>

<para>
When opening KWordQuiz, you will land on the welcome page. This page will list all the previously opened deck. Additionally it lets you create a new deck, open a deck from a file or download deck from the internet. Finally you can also choose which main mode you want to use.
</para>

<screenshot>
  <screeninfo>The Welcome Page</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="kwq-welcome.png" format="PNG" />
    </imageobject>
    <textobject>
      <phrase>The Welcome Page</phrase>
    </textobject>
  </mediaobject>
</screenshot>
</chapter>

<chapter id="editor">
<title>The Vocabulary Editor</title>

<para>
The vocabulary document area has the appearance of a spreadsheet-like grid. The grid consists of cells organized in two columns and a number of rows. Each column and row has a header. The column headers are used to specify the titles of the vocabulary document. They can be set by editing the first row.
</para>

<para>
You can click in a cell of the grid to make it the active cell. You can use the up and down arrow to move up and down in the table and tab to move to the next element.</para>

<screenshot>
  <screeninfo>The Vocabulary Editor</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="kwq-editor.png" format="PNG" />
    </imageobject>
    <textobject>
      <phrase>The Vocabulary Editor</phrase>
    </textobject>
  </mediaobject>
</screenshot>

<para>
In the document, you build a vocabulary of pair-wise entries in the two columns. You can enter text into the active cell simply by starting to type. The cell will now be in edit mode and you can select all or part of the text. You can also edit a cell by double-clicking it or by pressing <keycap>F2</keycap> and making changes directly in the cell.
</para>
<para>
When you have finished typing one entry, press the return key and the next cell will automatically become active. Hence, it's easy to quickly type several entries. There is really no limit to the number of rows you can have in a document.
</para>
</chapter>

<chapter id="flashcard">

<title>Flashcard Session</title>

<para>Select Flashcard from the navigation panel to start a flashcard session on the entries of the active vocabulary document. The mode selected in the <guimenu>Options</guimenu> menu will be used. If you change the options during a session, the session will be restarted.
</para>

<para>
If you are working with long expressions, the window can be resized to make more space available. The font size will also influence how much will fit in the different parts of the window.
</para>

<screenshot>
  <screeninfo>Flashcard Session</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="kwq-flashcard.png" format="PNG" />
    </imageobject>
    <textobject>
      <phrase>Flashcard Session</phrase>
    </textobject>
  </mediaobject>
</screenshot>
<para>
Initially the front of the card is displayed. Use the <guibutton>Check</guibutton> to see the other side.
</para>
<para>
To move on to the next card, either select <guibutton>I Know</guibutton> to count the card as correct or <guibutton>I Don't Know</guibutton> to count the card as incorrect.
</para>
<para>
Select <guibutton>Repeat Errors</guibutton> to repeat the cards you have counted as incorrect.
</para>
<para>
Select <guibutton>Try again</guibutton> to start the session from the beginning again. If you are using a random mode the cards will be reshuffled.
</para>
<para>
The score section at the top of the screen shows the number of cards, the number of cards you have seen, the number of cards counted as correct, and the number counted as incorrect.
</para>
</chapter>

<chapter id="multiple">

<title>Multiple Choice Session</title>

<para>
Select Multiple Choice in the welcome page to start a multiple choice quiz on the entries in the active vocabulary document. The mode selected in the <guimenu>Options</guimenu> menu will be used. If you change options during a session, the session will be restarted.
</para>
<para>
If you are working with long expressions the window can be resized to make more room. The font size (selected for the editor) will also influence how much will fit in the different parts of the window.
</para>
<para>
In the example below the user gave an incorrect answer to the previous question. He/she is now about to answer the next question.
</para>

<screenshot>
  <screeninfo>Multiple Choice Session</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="kwq-multiple.png" format="PNG" />
    </imageobject>
    <textobject>
      <phrase>Multiple Choice Session</phrase>
    </textobject>
  </mediaobject>
</screenshot>
<para>
Your choices are shown on the middle of the screen. Select the one you think is correct. Use <guibutton>Check</guibutton> to see if the answer is correct. If you have activated the automatic mode in <menuchoice><guimenu>Settings</guimenu></menuchoice> your selection is checked immediately.
</para>
<para>
Select <guibutton>Repeat Errors</guibutton> to repeat the cards you have counted as incorrect.
</para>
<para>
Select <guibutton>Try again</guibutton> to start the session from the beginning again. If you are using a random mode the cards will be reshuffled.
</para>
<para>
The score section at the top of the screen shows the number of questions, the number of questions you have answered, the number of correct answers, and the number of incorrect answers.
</para>
</chapter>


<chapter id="question-and-answer">

<title>Question &amp; Answer Session</title>
<para>
Select Question &amp; Answer from the navigation panel to start a question &amp; answer session on the entries in the active vocabulary. The mode selected in the <guimenu>Mode</guimenu> menu will be used. If you change mode during a session, the session will be restarted.
</para>
<para>
If you are working with long expressions, the window can be resized to make more room. The font size (selected for the editor) will also influence how much will fit in the different parts of the window.
</para>
<para>
In the example below the user gave a correct answer to the previous question (to see how incorrect answers are handled, see the <link linkend="multiple">Multiple Choice</link> chapter). He/she is now about to answer the next question.
</para>

<screenshot>
  <screeninfo>Question &amp; Answer Session</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="kwq-qanda.png" format="PNG" />
    </imageobject>
    <textobject>
      <phrase>Question &amp; Answer Session</phrase>
    </textobject>
  </mediaobject>
</screenshot>
<para>
Your question is shown on the center. Type your answer in the edit field. Use <guibutton>Check</guibutton> or &Enter; to see if the answer is correct.
</para>
<para>
Select <guibutton>Hint</guibutton> to get the next correct letter of the answer. In <menuchoice><guimenu>Settings</guimenu></menuchoice> you may choose to count any questions where you use the hint function as incorrect.
</para>
<para>
Select <guibutton>Repeat Errors</guibutton> to repeat the cards you have counted as incorrect.
</para>
<para>
Select <guibutton>Try again</guibutton> to start the session from the beginning again. If you are using a random mode the cards will be reshuffled.
</para>
<para>
The score section at the top of the screen shows the number of questions, the number of questions you have answered, the number of correct answers, and the number of incorrect answers.
</para>
</chapter>

<chapter id="fill-in-the-blank">
<title>Fill-in-the-blank</title>

<para>
'Fill-in-the-blank' is a powerful way to practice in &kwordquiz;. It is a special kind of question and answer quiz that needs to be described in more detail.
</para>

<para>
Consider the following table. It could be a vocabulary in &kwordquiz;:
</para>

<informaltable><tgroup cols="3">
<thead>
<row>
<entry></entry>
<entry>English</entry>
<entry>German</entry>
</row>
</thead>

<tbody>
<row>
<entry>1</entry>
<entry>We own a computer</entry>
<entry>Wir besitzen einen Computer</entry>
</row>

<row>
<entry>2</entry>
<entry>We own a computer</entry>
<entry>Wir [besitzen] einen Computer</entry>
</row>

<row>
<entry>3</entry>
<entry>We own a computer</entry>
<entry>Wir [besitzen einen] Computer</entry>
</row>

<row>
<entry>4</entry>
<entry>We own a computer</entry>
<entry>Wir [besitzen] einen [Computer]</entry>
</row>
</tbody>
</tgroup>
</informaltable>

<para>
The important thing to note is the placement of the brackets. They tell &kwordquiz; how the quiz should be performed.
</para>
<para>
In 1. there are no brackets. Assuming English is the question and German the answer you have to give the entire expression 'Wir besitzen einen Computer' for a correct answer.
</para>
<para>
In 2. &kwordquiz; would display the question but also 'Wir ........ einen Computer'. For a correct answer it is sufficient to write 'besitzen'.
</para>
<para>
3. shows that a blank can consist of more than one word. The correct answer is 'besitzen einen'.
</para>
<para>
In 4. there are two separate blanks. To specify that in the answer you have to write 'besitzen; Computer', &ie; separate the blanks with a semicolon in order to get a correct answer.
</para>
<para>
Marked blanks are only of relevance if they appear in the answer. Otherwise the brackets are ignored. Furthermore, brackets have no effect in multiple choice quizzes. To simplify the creation of 'Fill-in-the-blank' vocabularies there are menu commands to mark and unmark blanks. Of course you can also just type the brackets. &kwordquiz; checks the syntax. If the text appears in red there is something wrong with the brackets and a quiz cannot be started.
</para>
</chapter>

<chapter id="printing">
<title>Printing</title>
<para>
  &kwordquiz; provides the ability to print vocabulary documents in several different ways. The printing options are available in the &kwordquiz; editor. When selecting <guibutton>Print...</guibutton> you are presented with a menu where you can select to print the document as a vocabulary list (&ie; as displayed in the editor), a vocabulary exam, or as flashcards. Once the mode is selected, you will be presented with the standard &kde; print dialog.
</para>
<screenshot>
  <screeninfo>Vocabulary Printing Options</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="kwq-dlg-print-type.png" format="PNG" />
    </imageobject>
    <textobject>
      <phrase>Vocabulary Printing Options</phrase>
    </textobject>
  </mediaobject>
</screenshot>

<formalpara>
<title>Vocabulary list</title>
<para>The vocabulary will be printed as displayed in the editor. This includes font, row heights, and column widths. Make sure that the columns are narrow enough to fit on the page.</para>
</formalpara>
<screenshot>
  <screeninfo>Print Vocabulary List</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="kwq-dlg-print-list.png" format="PNG" />
    </imageobject>
    <textobject>
      <phrase>Print Vocabulary List</phrase>
    </textobject>
  </mediaobject>
</screenshot>

<formalpara>
<title>Vocabulary exam</title>
<para>The vocabulary will be printed as displayed in the editor, except that the right column will be left empty and a third column for scoring is added. Settings used include font, row heights, and column widths. Make sure that the columns are narrow enough to fit on the page.</para>
</formalpara>
<screenshot>
  <screeninfo>Print Vocabulary Exam</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="kwq-dlg-print-exam.png" format="PNG" />
    </imageobject>
    <textobject>
      <phrase>Print Vocabulary Exam</phrase>
    </textobject>
  </mediaobject>
</screenshot>

<formalpara>
<title>Flashcards</title>
<para> Two 3" x 5" cards per page. The cards will always be printed in landscape.</para>
</formalpara>
<screenshot>
  <screeninfo>Print Flashcards</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="kwq-dlg-print-flashcard.png" format="PNG" />
    </imageobject>
    <textobject>
      <phrase>Print Flashcards</phrase>
    </textobject>
  </mediaobject>
</screenshot>

</chapter>

<chapter id="dialogs">
<title>Dialogs</title>

<sect1 id="dlg-config-general">
<title>General Settings</title>
<screenshot>
  <screeninfo>General Settings</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="kwq-dlg-config.png" format="PNG" />
    </imageobject>
    <textobject>
      <phrase>General Settings</phrase>
    </textobject>
  </mediaobject>
</screenshot>
<para>
You can select what type of session a newly opened vocabulary should start in. Going directly to a quiz can prevent you from seeing any entries in advance.
</para>
<para>
For all sessions you can select if the scores should be displayed as percentages instead of absolute numbers.
</para>
<tip>
<para>
Note that the settings are automatically applied.
</para>
</tip>
</sect1>

<sect1 id="dlg-languages">
<title>Column Settings</title>
<para>You can open this dialog from the editor.</para>
<screenshot>
  <screeninfo>Column Settings</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="kwq-dlg-languages.png" format="PNG" />
    </imageobject>
    <textobject>
      <phrase>Column Settings</phrase>
    </textobject>
  </mediaobject>
</screenshot>
<para>
Use this dialog to define the column titles and column languages. Click on a language to selected it or close the dialog to discard any changes.
</para>
</sect1>
</chapter>

<chapter id="credits">

<title>Credits and License</title>

<para>
&kwordquiz;
</para>
<para>
Program copyright 2003-2008 Peter B. Hedlund <email>peter.hedlund@kdemail.net</email> 2023 Carl Schwan <email>carl@carlchwan.eu</email>
</para>

<para>
Documentation copyright 2003-2008 Peter B. Hedlund <email>peter.hedlund@kdemail.net</email>
</para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;   <!-- FDL: do not remove -->
&underGPL;   <!-- GPL License -->

</chapter>

&documentation.index;
</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes: nil
sgml-general-insert-case: lower
sgml-indent-step:0
sgml-indent-data:nil
End:
-->
