Debian Codegraph @

doc/index.docbook

raw
1 <?xml version="1.0" ?>
2 <!--
3 SPDX-FileCopyrightText: 2015 Andreas Cord-Lsandwehr <[email protected]>
4 SPDX-License-Identifier: CC-BY-SA-4.0
5 -->
6
7 <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [
8
9 <!ENTITY artikulate "Artikulate">
10 <!ENTITY kappname "&artikulate;">
11 <!ENTITY package "artikulate">
12 <!ENTITY % addindex "IGNORE">
13 <!ENTITY % English "INCLUDE">
14 ]>
15 <book id="artikulate" lang="&language;">
16
17 <bookinfo>
18 <title>The &artikulate; Handbook</title>
19 <authorgroup>
20 <author>
21 <personname>
22 <firstname>Andreas</firstname>
23 <surname>Cord-Landwehr</surname>
24 </personname>
25 <email>[email protected]</email>
26 </author>
27
28 <author>
29 <personname>
30 <firstname>Ondrila</firstname>
31 <surname>Gupta</surname>
32 </personname>
33 <email>[email protected]</email>
34 </author>
35
36 <!-- TRANS:ROLES_OF_TRANSLATORS -->
37 </authorgroup>
38
39 <copyright><year>2014-2015</year><holder>The &artikulate; Developers</holder></copyright>
40
41 <date>2015-09-27</date>
42 <releaseinfo>&artikulate; 0.6.0 (Applications 15.12)</releaseinfo>
43
44 <legalnotice>&FDLNotice;</legalnotice>
45
46 <abstract>
47 <para>
48 &artikulate; is a pronunciation trainer, designed to help in improving and perfecting pronunciation skills.
49 Learners train their pronunciation skills by recording their own voices and comparing those recording to native speaker recordings.
50 &artikulate; is part of the &kde; Education project.
51 </para>
52 </abstract>
53
54 <keywordset>
55 <keyword>KDE</keyword>
56 <keyword>kdeedu</keyword>
57 <keyword>language</keyword>
58 <keyword>course</keyword>
59 <keyword>unit</keyword>
60 <keyword>phrase</keyword>
61 </keywordset>
62
63 </bookinfo>
64
65 <chapter id="introduction">
66 <title>Introduction</title>
67 <para>
68 &artikulate; is a pronunciation trainer for improving and perfecting pronunciation skills for a non-native language.
69 For this, &artikulate; provides courses created by native speakers, who recorded their own voices as comparison material.
70 A student can download these recordings in form of courses from the Internet.
71 The training then consists of iterative playing of a native speaker's recording of some phrase, recording the own voice, and comparing both until the result is good enough to proceed with the next phrase.
72 </para>
73
74 <sect1 id="introduction-concept">
75 <title>The Learning Concept</title>
76 <para>
77 The study concept of &artikulate; is based on honest self-assessment of the student.
78 A student trains several phrases in one training session.
79 For each such phase, first he/she plays the native speaker recording for the phrase and listens to it.
80 Then, by recording his/her own voice when attempting to repeat this phrase, we get a second recording.
81 The student then can compare both recordings and either decides that the phrase is mastered or that another attempt is needed.
82 The provided courses provide trainings for special scenarios (like ordering food in a restaurant) but can also focus on learning how to pronounce difficult syllables and words of a particular language correctly.
83 </para>
84 </sect1>
85
86 <sect1 id="introduction-first-steps">
87 <title>First Steps in &artikulate;</title>
88 <para>
89 This chapter explains how to make the first steps in &artikulate;.
90 </para>
91
92 <sect2>
93 <title>1. Download a New Course</title>
94 <para>
95 You can download courses through <menuchoice><guimenu>File</guimenu> <guimenuitem>Download Courses</guimenuitem></menuchoice>.
96 If the menubar is not activated, you can open the <menuchoice><guimenu>File</guimenu></menuchoice> menu by clicking at the top-right button.
97 A download window will appear, listing the available languages provided by the &kde; Community.
98 You can sort through them using the order by functions at the right.
99 We download the Polish course by clicking on <guilabel>Install</guilabel>.
100 </para>
101 <screenshot>
102 <screeninfo>Download course.</screeninfo>
103 <mediaobject>
104 <imageobject>
105 <imagedata fileref="first-steps-3-download-course.png" format="PNG" />
106 </imageobject>
107 </mediaobject>
108 </screenshot>
109 </sect2>
110
111 <sect2>
112 <title>2. Start Training</title>
113 <para>
114 Courses consist of multiple training units, each usually grouping a set of phrases according to a scenario.
115 They can be switched by using the combo boxes for language and course at the top boarder of the screen.
116 </para>
117 <screenshot>
118 <screeninfo>Select unit and start training.</screeninfo>
119 <mediaobject>
120 <imageobject>
121 <imagedata fileref="first-steps-4-start-training.png" format="PNG" />
122 </imageobject>
123 </mediaobject>
124 </screenshot>
125 </sect2>
126
127 <sect2>
128 <title>Finish Training</title>
129 <para>
130 The training can be finished at any point by just closing the program.
131 </para>
132 </sect2>
133 </sect1>
134 </chapter>
135
136 <!--
137 <chapter id="screens">
138 <title>Screens</title>
139 <sect1 id="screens-training">
140 <title>The Training Screen</title>
141 <para>
142 The training view is the most important view in &artikulate;.
143 Whenever starting a training, this view is opened and will be presented until the training of the selected training unit is finished or the student stops the training.
144 In the center of this screen, there are controls for playing a native speaker recording, the text of the corresponding phrase, and controls to record and playback the student's own voice.
145 When a student judges to be done with training the pronunciation of the current phrase, by clicking <guilabel>OK</guilabel> the current phrase is marked as done and a next phrase is selected.
146 Otherwise, when clicking on <guilabel>Retry Later</guilabel>, a next phrase is selected but the current phrase will be displayed later again.
147 </para>
148
149 <para>
150 For training the pronunciation of a current phrase, the student shall first play the native speaker's recording by pressing at the <guilabel>Playback</guilabel> button at the left.
151 The next step is to press on the <guilabel>Record</guilabel> button and read the presented phrase aloud.
152 A further press on the <guilabel>Record</guilabel> button stops the recording and the recording can then be played with the corresponding <guilabel>Playback</guilabel> button.
153 By listening to both recordings, the student shall judge if the phrase was pronounced correctly or not.
154 If it was pronounced correctly, clicking on <guilabel>OK</guilabel> marks the phrase as learned and proceeds with the next phrase.
155 Otherwise, if not yet satisfied with the recording, the student either can retry recording by again clicking on <guilabel>Record</guilabel> or schedule the phrase for later training by clicking on <guilabel>Retry Later</guilabel>.
156 </para>
157
158 <para>
159 &artikulate;'s units are composed of a list of phrases of different lengths (words, expressions, sentences, and paragraphs).
160 A student can see the current learning progress at the bottom when looking at <link linkend="screens-training-progressbar">the progress bar</link>.
161 The progress bar also allows switching between phrases.
162 </para>
163
164 <para>
165 At any time, the student can choose to stop training by clicking at the <guilabel>Finish</guilabel> button.
166 </para>
167
168 <screenshot>
169 <screeninfo>The Training Screen.</screeninfo>
170 <mediaobject>
171 <imageobject>
172 <imagedata fileref="screen-training-overview.png" format="PNG" />
173 </imageobject>
174 <textobject>
175 <phrase>Screenshot of the Training Screen.</phrase>
176 </textobject>
177 </mediaobject>
178 </screenshot>
179
180 <sect2 id="screens-training-sound-controls">
181 <title>Sound Controls</title>
182 <itemizedlist>
183 <listitem><para>
184 <inlinemediaobject><imageobject>
185 <imagedata fileref="hi32-action-artikulate-media-record.png" format="PNG"/></imageobject>
186 </inlinemediaobject>
187 <guilabel>Record</guilabel>: Record your pronunciation through your microphone. Click again to stop recording.
188 </para></listitem>
189
190 <listitem><para>
191 <inlinemediaobject><imageobject>
192 <imagedata fileref="hi32-action-artikulate-media-playback-start.png" format="PNG"/></imageobject>
193 </inlinemediaobject>
194 <guilabel>Playback</guilabel>: Play a sound file. If active, click again to stop.
195 </para></listitem>
196
197 </itemizedlist>
198 </sect2>
199
200 <sect2 id="screens-training-learning-controls">
201 <title>Learning Controls</title>
202 <itemizedlist>
203 <listitem><para>
204 <inlinemediaobject><imageobject>
205 <imagedata fileref="training-ok.png" format="PNG"/></imageobject>
206 </inlinemediaobject>
207 <guilabel>OK</guilabel>: Mark current phrase as learned and continue with next phrase.
208 </para></listitem>
209
210 <listitem><para>
211 <inlinemediaobject><imageobject>
212 <imagedata fileref="training-retry.png" format="PNG"/></imageobject>
213 </inlinemediaobject>
214 <guilabel>Retry Later</guilabel>: Continue with training next phrase, but try this phrase later again.
215 </para></listitem>
216
217 <listitem><para>
218 <inlinemediaobject><imageobject>
219 <imagedata fileref="training-finish.png" format="PNG"/></imageobject>
220 </inlinemediaobject>
221 <guilabel>Stop</guilabel>: Stops the training and proceeds to the statistics view. Current training results are saved to training statistics.
222 </para></listitem>
223 </itemizedlist>
224 </sect2>
225
226 <sect2 id="screens-training-progressbar">
227 <title>Progress Bar</title>
228 <para>
229 The progress bar displays the learning progress for the current unit.
230 It consists of blocks representing the phrases in the current unit, whereas the color of a block explains the length of the phrase.
231 You can hover over these blocks to see the phrases and click on them to switch the currently trained phrase.
232 Dark elements are already trained, light ones are untrained.
233 </para>
234 <screenshot>
235 <screeninfo>Progress Bar</screeninfo>
236 <mediaobject>
237 <imageobject>
238 <imagedata fileref="screen-training-progressbar.png" format="PNG" />
239 </imageobject>
240 <textobject>
241 <phrase>The progress bar for the current unit.</phrase>
242 </textobject>
243 </mediaobject>
244 </screenshot>
245 <para>
246 On top of the progress bar you can see which type of phrases you are currently learning.
247 The available types are:
248 <itemizedlist>
249 <listitem><para>word: a single word, letter, or number</para></listitem>
250 <listitem><para>expression: an expression of several words that does not form a complete sentence</para></listitem>
251 <listitem><para>sentence: a complete sentence</para></listitem>
252 <listitem><para>paragraph: several sentences (usually 2-3) </para></listitem>
253 </itemizedlist>
254 </para>
255 </sect2>
256 </sect1>
257 </chapter>
258 -->
259 <chapter>
260 <title>Editor</title>
261 <para>
262 The integrated course editor is an advanced tool for language course contributors that allows the creation and collaborative work on language courses for &artikulate;.
263 On the one hand it allows the creation of language courses and recording of the native speaker sound files.
264 On the hand, it enables work on so called <emphasis>skeletons</emphasis>, which are language course prototypes that allow easy and fast creation of new courses derived from a prototype.
265 The editor only edits files outside of the training course set, i.e., the set of courses downloaded in &artikulate;.
266 </para>
267
268 <sect1>
269 <title>Overview</title>
270
271 <sect2>
272 <title>Editor Notions</title>
273 <para>
274 For the course editor we use a specific set of terms, which is also used for the following descriptions.
275 </para>
276 <variablelist>
277 <varlistentry>
278 <term>Language:</term>
279 <listitem>
280 <para>
281 Languages are only available in &artikulate; if they are given by language specifications.
282 </para>
283 </listitem>
284 </varlistentry>
285 <varlistentry>
286 <term>Course:</term>
287 <listitem>
288 <para>
289 A course is associated to one language and contains a list of units.
290 </para>
291 </listitem>
292 </varlistentry>
293 <varlistentry>
294 <term>Unit:</term>
295 <listitem>
296 <para>
297 A unit consists of phrases that are "somehow" homogeneous.
298 E.g. those can be phrases spoken in a restaurant or phrases spoken at a conversation at the street by a tourist searching for the way.
299 </para>
300 </listitem>
301 </varlistentry>
302 <varlistentry>
303 <term>Course Skeletons:</term>
304 <listitem>
305 <para>
306 A course skeleton forms the prototype of a course.
307 This is, skeletons help to ease creation of courses in several languages as they state a set of units and phrases (in English) that then can be used as a blueprint to create a course in a new language.
308 Updates of course skeletons can also be imported into courses that are created from a skeleton.
309 </para>
310 </listitem>
311 </varlistentry>
312 <varlistentry>
313 <term>Phrases:</term>
314 <listitem>
315 <para>
316 Phrases are given by a text string and a recording by a native speaker. We differ phrases by their lengths. The following phrase lengths exists
317 <itemizedlist>
318 <listitem>
319 <para><inlinemediaobject><imageobject>
320 <imagedata fileref="hi32-action-artikulate-word.png" format="PNG"/></imageobject>
321 </inlinemediaobject>
322 word: a single word, letter, or number</para>
323 </listitem>
324 <listitem>
325 <para><inlinemediaobject><imageobject>
326 <imagedata fileref="hi32-action-artikulate-expression.png" format="PNG"/></imageobject>
327 </inlinemediaobject>
328 expression: an expression of several words that does not form a complete sentence</para>
329 </listitem>
330 <listitem>
331 <para><inlinemediaobject><imageobject>
332 <imagedata fileref="hi32-action-artikulate-sentence.png" format="PNG"/></imageobject>
333 </inlinemediaobject>
334 sentence: a complete sentence</para>
335 </listitem>
336 <listitem>
337 <para><inlinemediaobject><imageobject>
338 <imagedata fileref="hi32-action-artikulate-paragraph.png" format="PNG"/></imageobject>
339 </inlinemediaobject>
340 paragraph: several sentences (usually 2-3)</para>
341 </listitem>
342 </itemizedlist>
343 </para>
344 </listitem>
345 </varlistentry>
346 </variablelist>
347 <para>
348 A course is associated with a specific language, consists of different units and each unit is given by a sequence of phrases in different lengths.
349 </para>
350 </sect2>
351
352 <sect2>
353 <title>Set Storage Folder/Course Repository</title>
354 <para>
355 The editor operates within a separate folder (in the following called <emphasis>repository</emphasis>, as it is recommended to be under some version control system).
356 In that folder, the editor searches for editable courses and skeleton files and also stores new files.
357 </para>
358 <para>
359 The course repository can be set in the configuration dialog.
360 It can be found at <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure &artikulate;</guimenuitem></menuchoice> and the course settings are at the menu option <guilabel>Course Resources</guilabel>.
361 </para>
362 <screenshot>
363 <screeninfo>Set course repository for editor.</screeninfo>
364 <mediaobject>
365 <imageobject>
366 <imagedata fileref="editor-set-repository.png" format="PNG" />
367 </imageobject>
368 <caption><para>Set course repository for editor.</para></caption>
369 </mediaobject>
370 </screenshot>
371 </sect2>
372 </sect1>
373
374 <!--<sect1>TODO needs complete rewrite
375 <title>Edit a Course</title>
376 <para>
377 The editor can be started from the main menu with <menuchoice><guimenu>Mode</guimenu> <guimenuitem>Course Editor mode</guimenuitem></menuchoice>.
378 There you have the options to work on existing skeleton files or to create new courses or edit existing ones.
379 After selecting a language, you can open an existing course to edit it, or otherwise use <guilabel>New Course</guilabel> to create a new course for this language.
380 In either case, you will be presented the list of units of the course, where you can create new units or open existing ones for edit.
381 </para>
382
383 <sect2>
384 <title>Edit a Unit</title>
385 <para>
386 When opening a unit for editing, you will see the list of its phrases (see below).
387 One line of this list contains the following information:
388 <orderedlist>
389 <listitem><para>edit button: open this phrase for edit</para></listitem>
390 <listitem><para>phrase type: icon that denotes the type of this phrase (e.g., word, expression)</para></listitem>
391 <listitem><para>edit state: a colored block that denotes the edit state of this phrase (red: unknown/no state set; orange: translated state; green: completed state)</para></listitem>
392 <listitem><para>the phrase</para></listitem>
393 <listitem><para>exclude button: if course derives from a course skeleton, this button allows excluding the phrase from the unit</para></listitem>
394 </orderedlist>
395 </para>
396 <screenshot>
397 <screeninfo>Editor View: list of phrases within a unit.</screeninfo>
398 <mediaobject>
399 <imageobject>
400 <imagedata fileref="editor-screenshot-unit.png" format="PNG" />
401 </imageobject>
402 <caption><para>Editor View: list of phrases within a unit.</para></caption>
403 </mediaobject>
404 </screenshot>
405 </sect2>
406
407 <sect2>
408 <title>Edit a Phrase</title>
409 <para>
410 When opening a phrase for editing, you will see the phrase editor as shown below.
411 This edit interface contains the following elements:
412 </para>
413 <itemizedlist>
414 <listitem><para>the phrase text as it will be shown in the trainer</para></listitem>
415 <listitem><para>the original phrase, if using a course skeleton</para></listitem>
416 <listitem><para>the edit state of the phrase</para></listitem>
417 <listitem><para>the type/length of the phrase</para></listitem>
418 <listitem><para>recording buttons for the native speaker recordings</para></listitem>
419 <listitem><para>buttons to denote interesting phonemes of the phrase (currently not used in training mode)</para></listitem>
420 </itemizedlist>
421 <para>
422 You can close the phrase editing interface with
423 <inlinemediaobject><imageobject>
424 <imagedata fileref="editor-apply.png" format="PNG"/></imageobject>
425 </inlinemediaobject>
426 to accept the changes you did, or with
427 <inlinemediaobject><imageobject>
428 <imagedata fileref="editor-cancel.png" format="PNG"/></imageobject>
429 </inlinemediaobject>
430 to discard your changes.
431 </para>
432 <screenshot>
433 <screeninfo>Editor View: editing view for a phrase.</screeninfo>
434 <mediaobject>
435 <imageobject>
436 <imagedata fileref="editor-screenshot-editing-phrase.png" format="PNG" />
437 </imageobject>
438 <caption><para>Editor View: editing view for a phrase.</para></caption>
439 </mediaobject>
440 </screenshot>
441 </sect2>
442
443 <sect2>
444 <title>Update from Course Prototype</title>
445 <para>
446 If the currently edited course derives from a skeleton, then the course can be updated from the latest version of the skeleton by using the button <guilabel>Update from Course Prototype</guilabel> at the top left of the screen.
447 This button is deactivated if the course is not derived from a course skeleton.
448 </para>
449 </sect2>
450 </sect1>-->
451 </chapter>
452
453
454 <chapter id="credits">
455 <title>Credits and License</title>
456
457 <para>
458 &artikulate;
459 </para>
460 <para>Program Copyright:</para>
461 <itemizedlist>
462 <listitem><para>Copyright 2013-2015 Andreas Cord-Landwehr</para></listitem>
463 <listitem><para>Copyright 2013 Oindrila Gupta</para></listitem>
464 <listitem><para>Copyright 2013 Magdalena Konkiewitz</para></listitem>
465 <listitem><para>Copyright 2013-2014 Samikshan Bairagya</para></listitem>
466 </itemizedlist>
467
468 <para>Documentation Copyright:</para>
469 <itemizedlist>
470 <listitem><para>Copyright 2014-2015 Andreas Cord-Landwehr</para></listitem>
471 </itemizedlist>
472
473 <!-- TRANS:CREDIT_FOR_TRANSLATORS -->
474 &underFDL; <!-- FDL: do not remove -->
475 &underGPL; <!-- GPL License -->
476
477 </chapter>
478
479 &documentation.index;
480 </book>
481 <!--
482 Local Variables:
483 mode: sgml
484 sgml-minimize-attributes: nil
485 sgml-general-insert-case: lower
486 sgml-indent-step:0
487 sgml-indent-data:nil
488 End:
489 -->