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

<bookinfo>
<title
>El manual del &minuet;</title>

<authorgroup>
<author
><personname
> <firstname
>Sandro</firstname
> <othername
>S.</othername
> <surname
>Andrade</surname
> </personname
> <email
>&Sandro.Andrade.mail;</email
> </author>
&traductor.Antoni.Bella; 
</authorgroup>

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

<date
>17 de gener de 2016</date>

<releaseinfo
>Minuet 00.01 (Aplicacions 16.04)</releaseinfo>

<abstract>
<para
>El &minuet; és una aplicació per a l'educació musical. Disposa d'un conjunt d'exercicis d'entrenament de l'oïda referits a intervals, acords, escales i altres. </para>
</abstract>

<keywordset>
<keyword
>KDE</keyword>
<keyword
>kdeedu</keyword>
<keyword
>música</keyword>
<keyword
>educació</keyword>
<keyword
>intervals</keyword>
<keyword
>acords</keyword>
<keyword
>escales</keyword>
<keyword
>minuet</keyword>
</keywordset>

</bookinfo>

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

<!-- The introduction chapter contains a brief introduction for the
application that explains what it does and where to report
problems. Basically a long version of the abstract.  Don't include a
revision history. (see installation appendix comment) -->

<para
>Benvingut al &minuet;: el programari &kde; per a educació musical. L'objectiu del &minuet; és ajudar als estudiants i professors en molts aspectes de l'educació musical, com l'entrenament de l'oïda, la lectura a primera vista, el solfeig, les escales, el ritme, l'harmonia i la improvisació. El &minuet; fa un ampli ús de les capacitats &MIDI; per a proporcionar un conjunt complet de característiques relatives al canvi de volum, tempo i to, el qual fa del &minuet; una valuosa eina per als músics principiants i experimentats. </para>
<para
>El &minuet; ofereix un ric conjunt d'exercicis d'entrenament de l'oïda i se n'hi poden afegir de nous de forma transparent amb la finalitat d'estendre les seves funcionalitats i adaptar-lo a diversos contextos de l'educació musical. </para>
<para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="minuet-screenshot.png"/></imageobject>
<caption
><para
>Exercicis d'acords per a l'entrenament de l'oïda amb el &minuet;</para
></caption>
</mediaobject>
</para>
</chapter>

<chapter id="using-minuet">
<title
>Ús del &minuet;</title>

<para
>En les següents tres seccions: <link linkend="starting-minuet"
>Començar amb el &minuet;</link
>, <link linkend="midi-configuration-wizard"
>Assistent de configuració del &minuet;</link
> i <link linkend="minuet-exercises"
>Exercicis i flux de treball amb el &minuet;</link
> donarem els passos necessaris per a posar el &minuet; en funcionament. </para>

<sect1 id="starting-minuet">
<title
>Començar amb el &minuet;</title>
<para
>Podeu iniciar el &minuet; des del llançador d'aplicacions. Obriu el menú de programes del &kde; fent clic a la icona del llançador d'aplicacions a la barra d'eines a la part inferior esquerra de la pantalla. Això elevarà un menú. Moveu el cursor fins a l'element <menuchoice
><guimenu
>Aplicacions</guimenu
><guisubmenu
>Educació</guisubmenu
><guisubmenu
>Miscel·lània</guisubmenu
> <guimenuitem
>&minuet; (Programari d'educació musical)</guimenuitem
></menuchoice
> del menú. </para>
</sect1>

<sect1 id="midi-configuration-wizard">
<title
>Assistent de configuració del &minuet;</title>
<para
>Quan executeu el &minuet; per primera vegada, apareixerà un assistent de configuració que verificarà si totes les dependències requerides per a gestionar els fitxers &MIDI; es troben al seu lloc en el sistema. El &minuet; utilitza <ulink url="http://timidity.sourceforge.net/"
>TiMidity++</ulink
>/<ulink url="http://freepats.zenvoid.org/"
>Freepats</ulink
> com a dorsal &MIDI; per omissió. Per tant, l'assistent de configuració avalua si aquestes tecnologies estan correctament instal·lades i configurades. </para>
<para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="configuration-wizard.png"/></imageobject>
<caption
><para
>Primer inici del &minuet; amb l'Assistent de configuració</para
></caption>
</mediaobject>
</para>
<para
>L'assistent de configuració haurà de passar amb èxit totes les proves, el &minuet; s'iniciarà automàticament i aturarà el TiMidity++ durant l'inici i finalització de l'aplicació, respectivament. Podreu executar l'assistent de configuració de nou en qualsevol moment, accedint a <menuchoice
> <guimenu
>Arranjament</guimenu
> <guimenuitem
>Executa l'assistent de configuració</guimenuitem
> </menuchoice
>. </para>
</sect1>

<sect1 id="minuet-exercises">
<title
>Exercicis i flux de treball amb el &minuet;</title>

<para
>La interfície d'usuari del &minuet; implica quatre components principals: </para>
<para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="minuet-ui-components.png"/></imageobject>
<caption
><para
>Components de la IU del &minuet;</para
></caption>
</mediaobject>
</para>
<variablelist>

<varlistentry>
<term
><guimenuitem
>Menú de navegació</guimenuitem
></term>
<listitem
><para
>Permet navegar per les categories d'exercicis del &minuet; i la selecció d'un exercici en particular. El menú de navegació s'ha creat de forma dinàmica en base als fitxers d'especificació dels exercicis tal com es descriu a <link linkend="creating-exercises"
>Crear els exercicis</link
>. Els exercicis del &minuet; estan agrupats segons les classes, com ara intervals, escales i acords.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><guimenuitem
>Controls del reproductor MIDI</guimenuitem
></term>
<listitem
><para
>Proporciona les funcionalitats bàsiques per al maneig de la reproducció &MIDI;. El &minuet; és capaç de reproduir fitxers &MIDI; de forma arbitrària seleccionant <menuchoice
> <guimenu
>Fitxer</guimenu
> <guimenuitem
>Obre</guimenuitem
> </menuchoice
> i després fent clic al botó <parameter
>reprodueix</parameter
> <inlinemediaobject
><imageobject
><imagedata fileref="multimedia-play.png"/></imageobject
></inlinemediaobject
>. L'execució es pot pausar fent clic al botó <parameter
>pausa</parameter
> <inlinemediaobject
><imageobject
><imagedata fileref="multimedia-pause.png"/></imageobject
></inlinemediaobject
> i reprendre de nou fent clic al botó <parameter
>reprodueix</parameter
>. El botó <parameter
>atura</parameter
> <inlinemediaobject
> <imageobject
><imagedata fileref="multimedia-stop.png"/></imageobject
></inlinemediaobject
> interromp la reproducció &MIDI;. Els controls del reproductor &MIDI; també proporcionen controls lliscants per a canviar el volum <inlinemediaobject
><imageobject
><imagedata fileref="multimedia-volume.png"/></imageobject
></inlinemediaobject
>, temps <inlinemediaobject
><imageobject
><imagedata fileref="multimedia-speed.png"/></imageobject
></inlinemediaobject
> i to <inlinemediaobject
><imageobject
><imagedata fileref="multimedia-pitch.png"/></imageobject
></inlinemediaobject
> de la reproducció &MIDI; actual. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><guimenuitem
>Vista del teclat</guimenuitem
></term>
<listitem
><para
>Mostra els esdeveniments de la <parameter
>nota activa</parameter
> del &MIDI; seqüenciats a partir d'un fitxer &MIDI; o de l'execució d'un exercici.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><guimenuitem
>Vista de l'exercici</guimenuitem
></term>
<listitem
><para
>Presenta, per a un exercici determinat, els botons per a controlar la presentació de l'exercici i un conjunt de possibles respostes a l'exercici. Un exercici comença fent clic al botó <parameter
>pregunta nova</parameter
>. Se selecciona un interval/acord/escala aleatòriament que serà reproduït pel &minuet; i després s'espera que l'estudiant triï una resposta entre les que es mostren a la graella de resposta. El &minuet; sempre presenta -com un petit cercle blanc a la vista del teclat- la primera nota de l'interval/escala seleccionada o la nota base de l'acord seleccionat. En passar per sobre d'una possible resposta, el &minuet; ressaltarà la seva representació visual corresponent a la vista del teclat. Les notes restants de la resposta ressaltada es presentaran com a petits cercles, on els colors seran els mateixos que el del botó de resposta ressaltat. L'estudiant pot escoltar de nou l'exercici fent clic al botó <parameter
>reprodueix la pregunta</parameter
>, feu clic al botó de la resposta escollida, o abasteu la resposta correcta fent clic al botó <parameter
>renuncio</parameter
>. Pot començar una nova execució del mateix exercici prement el botó <parameter
>pregunta nova</parameter
> una altra vegada.</para
></listitem>
</varlistentry>

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

<chapter id="creating-exercises">
<title
>Crear exercicis nous per al &minuet;</title>

<para
>Els exercicis del &minuet; es defineixen en fitxers d'especificació dels exercicis, escrits en el format JSON: </para>
<para>
<programlisting
>{
  "exercises": [
    {
      "name": "Intervals",
      "root": "21..104",
      "playMode": "scale",
      "children": [
        {
          "name": "Ascending Melodic Intervals",
          "children": [
            {
              "name": "Seconds",
              "options": [
                {
                  "name": "Minor Second",
                  "sequenceFromRoot": "1"
                },
                {
                  "name": "Major Second",
                  "sequenceFromRoot": "2"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
</programlisting>
</para>
<para
>Els fitxers d'especificació dels exercicis del &minuet; contenen un objecte JSON de nivell superior que ofereix la matriu dels <parameter
>exercicis</parameter
>. Aquesta matriu defineix una estructura jeràrquica pels exercicis, agrupats per categories. Cada categoria/exercici té un nom. Els objectes JSON de la categoria contenen una propietat anomenada <parameter
>children</parameter
> (filla), que descriu les subcategories/exercicis que conté aquesta categoria. Els objectes JSON de l'exercici contenen una propietat anomenada <parameter
>options</parameter
> (opcions), la qual defineix les possibles respostes per a aquest exercici. En cada execució dels exercicis, el &minuet; selecciona aleatòriament una resposta entre totes les possibles, i s'espera que l'alumne faci clic al botó de la resposta que correspongui amb la resposta seleccionada. </para>
<para
>Qualsevol sub/categoria pot definir un paràmetre <parameter
>root</parameter
> (base) que defineix l'interval des del qual la nota inicial de l'interval/acord/escala serà escollit aleatòriament per a tots els exercicis en aquesta categoria. Aquest interval es correspon amb els estàndards números de nota &MIDI; i segueix el format  <parameter
>&lt;min-value&gt;..&lt;max-value&gt;</parameter
>. L'exemple presentat anteriorment utilitza tot l'interval del teclat com a possibles notes base (21..104). El paràmetre <parameter
>playMode</parameter
> indica com s'han de reproduir les possibles respostes: com una <parameter
>scale</parameter
> (-escala- una nota després de l'altra) o com una <parameter
>chord</parameter
> (-acord- totes les notes sonant simultàniament). </para>
<para
>Cada opció de l'exercici defineix un nom i la seqüència de notes que s'han de reproduir a partir de la nota base seleccionada aleatòriament en cada exercici executat. Aquesta seqüència de notes es defineix com a distàncies relatives a partir de la nota base, descrivint l'interval que cada nota forma en conjunció amb la nota base. Per exemple, per a una escala major, la seqüència de notes és <quote
>2 4 5 7 9 11 12</quote
>, el que denota respectivament un estructura de l'escala major <quote
>completa completa mitja completa completa completa mitja</quote
>. El paràmetre <parameter
>sequenceFromRoot</parameter
> pot contenir qualsevol nombre de notes en longitud. També, el nucli del &minuet; garanteix que només les respostes en que totes les notes es troben dins de l'interval del teclat són seleccionades aleatòriament. </para>
<para
>Per a proporcionar una millor infraestructura per a l'organització d'un gran conjunt de fitxers d'especificació dels exercicis, el nucli del &minuet; utilitza diversos fitxers d'especificació, els quals es fusionen de forma automàtica per a compondre la jerarquia final de l'exercici presentada al menú de navegació. Els exercicis es fusionen correctament ja que els diferents fitxers d'especificació utilitzen el mateix nom de la sub/categoria en la definició dels exercicis. Per ara, el &minuet; no proporciona cap &IGU; per a la creació d'especificacions dels exercicis, de manera que haureu de crear manualment aquests fitxers JSON. Els fitxers d'especificació dels exercicis del &minuet; es poden instal·lar a tot el sistema en el directori <filename
>/usr/share/minuet/exercises/</filename
> o localment al directori <filename
>~/.local/share/minuet/exercises/</filename
>. </para>

</chapter>

<chapter id="minuet-configuration">
<title
>Configuració del &minuet;</title>

<para
>Alguns ajustaments &MIDI; del &minuet; es poden configurar a <menuchoice
> <guimenu
>Arranjament</guimenu
> <guimenuitem
>Configura el &minuet;</guimenuitem
> </menuchoice
>: </para>
<para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="minuet-configuration.png"/></imageobject>
<caption
><para
>Ajustaments del &minuet;</para
></caption>
</mediaobject>
</para>
<para
>El paràmetre <parameter
>TiMidity++</parameter
> conté el camí absolut al programa TiMidity++. Aquest camí es pot ser ajustat automàticament per l'assistent de configuració del &minuet; si el vostre entorn està sa, però si ho voleu, podeu proporcionar la vostra pròpia configuració. </para>
<para
>Els <parameter
>paràmetres del TiMidity++</parameter
> especifiquen els que s'utilitzaran quan s'inicia el servei TiMidity++. Haureu d'utilitzar el valor proporcionat per l'assistent de configuració del &minuet;, llevat que tingueu una bona raó per canviar-lo. </para>
<para
>Finalment, el paràmetre <parameter
>port de sortida MIDI</parameter
> indica el port que haurà d'utilitzar el &minuet; per a reproduir els esdeveniments &MIDI;. Un cop més, l'assistent de configuració del &minuet; dóna millors valors, però sou lliure de canviar-ho si s'utilitza un altra seqüenciador &MIDI; com, per exemple, <quote
>fluidsynth</quote
>. </para>

</chapter>

<chapter id="credits">

<title
>Crèdits i llicència</title>

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

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

<para
>Traductor de la documentació: &credits.Antoni.Bella;</para
> 
&underFDL; &underGPL; </chapter>

<appendix id="installation">
<title
>Instal·lació</title>

<sect1 id="requirements">
<title
>Requeriments</title>

<!--
List any special requirements for your application here. This should include:
.Libraries or other software that is not included in kdesupport or kf5
.Hardware requirements like amount of RAM, disk space, graphics card
capabilities, screen resolution, special expansion cards, etc.
.Operating systems the app will run on. If your app is designed only for a
specific OS, (you wrote a graphical LILO configurator for example) put this
information here.
-->

<para
>Per tal d'utilitzar amb èxit el &minuet;, necessitareu unes poques biblioteques de les &kf5; 5.18 (CoreAddons, I18n, XmlGui, ConfigWidgets, DocTools, KIO). A més, el &minuet; es basa en la <ulink url="http://drumstick.sourceforge.net/"
>biblioteca Drumstick</ulink
> per a les capacitats &MIDI;. </para>

</sect1>

</appendix>

&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;
-->
