<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [
  <!ENTITY Sandro.Andrade '<personname
><firstname
>Sandro</firstname
><surname
>Andrade</surname
></personname
>'>
  <!ENTITY Sandro.Andrade.mail '<email
>sandroandrade@kde.org</email
>'>
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % Spanish "INCLUDE">
]>
<book id="minuet" lang="&language;">

<bookinfo>
<title
>Manual de &minuet;</title>

<authorgroup>
<author
><personname
> <firstname
>Sandro</firstname
> <othername
>S.</othername
> <surname
>Andrade</surname
> </personname
> <email
>&Sandro.Andrade.mail;</email
> </author>
<othercredit role="translator"
><firstname
>Eloy</firstname
><surname
>Cuadra</surname
><affiliation
><address
><email
>ecuadra@eloihr.net</email
></address
></affiliation
><contrib
>Traductor</contrib
></othercredit
> 
</authorgroup>

<copyright>
<year
>2016</year>
<holder
>&Sandro.Andrade;</holder>
</copyright>
<legalnotice
>&FDLNotice;</legalnotice>

<date
>2016-12-09</date>

<releaseinfo
>Applications 16.12</releaseinfo>

<abstract>
<para
>&minuet; es una aplicación para el aprendizaje musical. Contiene un conjunto de ejercicios de entrenamiento auditivo que contemplan el uso de intervalos, acordes y escalas. </para>
</abstract>

<keywordset>
<keyword
>KDE</keyword>
<keyword
>kdeedu</keyword>
<keyword
>música</keyword>
<keyword
>educativo</keyword>
<keyword
>intervalos</keyword>
<keyword
>acordes</keyword>
<keyword
>escalas</keyword>
<keyword
>minuet</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
<title
>Introducción</title>

<para
>Welcome to &minuet;: the &kde; software for music education. &minuet; aims at supporting students and teachers in many aspects of music education, such as ear training, first-sight reading, solfa, scales, rhythm, harmony, and improvisation. &minuet; makes extensive use of &MIDI; capabilities to provide a full-fledged set of features regarding volume, tempo, and pitch changes, which makes &minuet; a valuable tool for both novice and experienced musicians. </para>
<para
>&minuet; incluye un extenso conjunto de ejercicios para entrenamiento del oído y permite <link linkend="creating-exercises"
>añadir fácilmente</link
> otros nuevos para poder extender sus funciones y adaptarlo a diversos contextos de educación musical. </para>
<para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="minuet-screenshot.png"/></imageobject>
<caption
><para
>Ejercicios de acordes de &minuet; para entrenamiento auditivo</para
></caption>
</mediaobject>
</para>
</chapter>

<chapter id="using-minuet">
<title
>Uso de &minuet;</title>

<para
>En las dos siguientes secciones (<link linkend="starting-minuet"
>Inicio de &minuet;</link
> y <link linkend="minuet-exercises"
>Ejercicios de &minuet;</link
>) le proporcionaremos los pasos necesarios para empezar a usar &minuet;. </para>

<sect1 id="starting-minuet">
<title
>Inicio de &minuet;</title>
<para
>You can start &minuet; from the application launcher. Open the &kde; program menu by clicking on the application launcher icon on the toolbar at the bottom left of your screen. This will raise a menu. Move your cursor up the menu to the <menuchoice
><guimenu
>Applications</guimenu
><guisubmenu
>Education</guisubmenu
><guisubmenu
>Miscellaneous</guisubmenu
> <guimenuitem
>&minuet; (Music Education Software)</guimenuitem
></menuchoice
> menu item. </para>
</sect1>

<sect1 id="minuet-exercises">
<title
>Ejercicios y flujo de trabajo en &minuet;</title>

<para
>La interfaz de usuario de &minuet; contiene tres componentes principales: </para>
<para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="minuet-ui-components.png"/></imageobject>
<caption
><para
>Componentes de la interfaz de usuario de &minuet;</para
></caption>
</mediaobject>
</para>
<variablelist>

<varlistentry>
<term
><guimenuitem
>Menú de navegación</guimenuitem
></term>
<listitem
><para
>Le permite desplazarse por las categorías de ejercicios de &minuet; y seleccionar un determinado ejercicio. El menú de navegación se crea de forma dinámica según los archivos de especificación de ejercicios, como se describe en <link linkend="creating-exercises"
>Creación de ejercicios</link
>. Los ejercicios de &minuet; se agrupan según su clase, como intervalos, escalas y acordes.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><guimenuitem
>Vista del teclado</guimenuitem
></term>
<listitem
><para
>Expone los eventos &MIDI; <parameter
>note on</parameter
> secuenciados por la ejecución de un archivo &MIDI; o de un ejercicio.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><guimenuitem
>Vista de ejercicios</guimenuitem
></term>
<listitem
><para
>Presents, for a given exercise, buttons for controlling exercise presentation and a set of exercise's possible answers. An exercise run begins by clicking the <parameter
>new question</parameter
> button. A randomly selected interval/chord/scale is played by &minuet; and then the student is expected to pick up an answer among the ones shown in the answer's grid. &minuet; always present - as a white small circle in Keyboard View - the first note of selected interval/scale or the root note of selected chord. By hovering a possible answer, &minuet; highlights its corresponding visual representation in Keyboard View. The remaining notes of the hovered answer are presented as small circles whose colors are the same of hovered answer's button. The student can hear the exercise again by clicking the <parameter
>play question</parameter
> button, click the chosen answer button, or get the right answer by clicking the <parameter
>give up</parameter
> button. A new run of the same exercise can be started by clicking again the <parameter
>new question</parameter
> button.</para
></listitem>
</varlistentry>

</variablelist>
</sect1>
</chapter>

<chapter id="creating-exercises">
<title
>Creación de nuevos ejercicios de &minuet;</title>

<para
>&minuet;'s exercises are defined in exercise specification files, written in JSON format: </para>
<para>
<programlisting
>{
  "exercises": [
    {
      "name": "Intervalos",
      "root": "21..104",
      "playMode": "scale",
      "children": [
        {
          "name": "Intervalos melódicos ascendentes",
          "children": [
            {
              "name": "Segundas",
              "options": [
                {
                  "name": "Segunda menor",
                  "sequenceFromRoot": "1"
                },
                {
                  "name": "Segunda mayor",
                  "sequenceFromRoot": "2"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
</programlisting>
</para>
<para
>&minuet;'s exercise specification files contain one top-level JSON object featuring the <parameter
>exercises</parameter
> array. Such an array defines a hierarchical structure of exercises, grouped by categories. Every category/exercise has a name. Category JSON objects contain a property named <parameter
>children</parameter
>, which describes the subcategories/exercises entailed by such a category. Exercise JSON objects contain a property named <parameter
> options</parameter
>, which defines the possible answers for such an exercise. In each exercise run, &minuet; randomly selects one answer among the possible ones and the student is expected to click the answer's button which corresponds to the selected answer. </para>
<para
>Cualquier (sub)categoría puede definir un parámetro <parameter
>root</parameter
> para indicar el intervalo del que se escogerá al azar la nota inicial del intervalo, acorde o escala para todos los ejercicios de dicha categoría. Este intervalo corresponde a los números de notas &MIDI; estándares y sigue el formato <parameter
>&lt;valor-mín&gt;..&lt;valor-máx&gt;</parameter
>. El ejemplo mostrado anteriormente usa todo el intervalo del teclado como posibles notas raíz (21..104). El parámetro <parameter
>playMode</parameter
> indica cómo se deben reproducir las posibles respuestas: como una <parameter
>escala</parameter
> (una nota tras otra) o como un <parameter
>acorde</parameter
> (todas las notas sonando simultáneamente). </para>
<para
>Each exercise's option defines a name and the sequence of notes which should be played from the root note randomly selected in each exercise run. Such sequence of notes is defined as relative distances from the root note, describing the interval each note forms in conjunction with the root note. For example, for a major scale, the sequence of notes is "2 4 5 7 9 11 12", which respectively denotes the "whole whole half whole whole whole half" major scale structure. The <parameter
>sequenceFromRoot</parameter
> parameter may contain any notes in length. Also, &minuet;'s core ensures that only answers whose all notes lies within keyboard range are randomly selected. </para>
<para
>To provide a better infrastructure for organizing a large set of exercise specification files, &minuet;'s core supports the use of several specification files, which are automatically merged to compose the final exercise hierarchy presented in the Navigation Menu. Exercises are correctly merged as long as different specification files use the same (sub)category name when defining exercises. For now, &minuet;'s provides no &GUI; for creating exercise specifications so that you must manually create such JSON files. &minuet;'s exercise specification files may be installed system-wide or locally in the <filename class="directory"
>minuet/exercises/</filename
> directory located in <userinput
><command
>qtpaths</command
> <option
>--path GenericDataLocation</option
></userinput
> </para>

</chapter>

<chapter id="credits">

<title
>Créditos y licencia</title>

<para
>&minuet; </para>
<para
>Copyright del programa 2016 &Sandro.Andrade; &Sandro.Andrade.mail; </para>

<para
>Copyright de la documentación &copy; 2016 &Sandro.Andrade; &Sandro.Andrade.mail; </para>

<para
>Traducido por Eloy Cuadra <email
>ecuadra@eloihr.net</email
>.</para
> &underFDL; &underGPL; </chapter>

&documentation.index;
</book>

<!--
Local Variables:
mode: xml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:

vim:tabstop=2:shiftwidth=2:expandtab
kate: space-indent on; indent-width 2; tab-width 2; indent-mode none;
-->
