## Lesson files

Si desea escribir lecciones, my consejo es que le de un vistazo a algunos de los archivos en `lesson-files/` y use este documento y la especificación del formato musical para referencia. Para usar estos archivos de lecciones, deberña guardarlos en `$HOME/lessonfiles/`.

### Contenido de los archivos de lecciones

Un archivo de lecciones contiene un segmento de cabecera y uno o más bloques de preguntas:

    header {
      ASSIGNACION
      ASSIGNACION
      ...
    }
    question {
      ASSIGNACION
      ...
    }

### Bloque de cabecera

El bloque de cabecera puede ser colocado en cualquier parte del archivo, pero por convención debería ser el primer bloque del archivo. Si se encuentra más de un bloque de cabecera, por ejemplo cuando se use `include`, sólamente se usará el primer bloque de cabecera, y el resto se ignorará.

Definiciones para ponerse en el bloque de cabecera:

`version = STRING`

  Mostrar la versión de Solfege más antigua con la que se sabe que la lección funciona. Por ejemplo `version = "1.1.1"`. Esta variable no es requerida, pero se debería usar porque puede ayudar (pero no garantizar) a evitar problemas si el formato de lecciones cambia en el futuro.

`title = STRING`

  Descripción corta en línea.

`description = STRING`

  Descripción más larga que puede contener etiquetas html.

`content = LIST`

  Posibles valores: `chord`, `dictation`, `id-by-name`, `harmony` and `sing-chord`

  Algunas lecciones pueden ser útiles para más de un ejercicio. Por ejemplo, un archivo con acordes se puede usar por el ejercicio id-by-name, y debe contener: `content = chord, id-by-name`

`musicformat = normal | chord`
  `normal`

    The default value.

  `chord`

    Cualquier música "MUSIC CODE" se interpretará como:

        \staff{ < MUSIC CODE > }

    or:

        \staff\transpose NOTENAME{ < MUSIC CODE > }

    El formato de `chord` es necesario si las lecciones deben usar ejercicios escritos para esta lección, por ejemplo el ejercicio id-by-name.

  `satb`

    La literal musical `"c | bes g | e | G C"` se interpretará como:

        \staff{ \stemUp < c > }
        \addvoice{ \stemDown < bes g > }
        \staff{\clef bass; \stemUp < e > }
        \addvoice{ \stemDown < G C > }

    Esto se usa por el ejercicio sing-chord exercise.

`random_transpose = integer, integer | no | yes`

  (Default: no) En algunos ejercicios se puede transportar la música para crear variaciones. La variable se ignora en ejercicios que no soporten el transporte.

  Si usa el formato con dos enteros, los enteros definen el rango aceptable para la transposición. Si escribe `random_transpose = -5, 12` la música se transportará a no más de 5 semitonos hacia abajo o 12 semitonos hacia arriba (una octava).

  `random_transpose = yes` es lo mismo que: `random_transpose = -5, 6` y `random_transpose = no` es lo mismo que `random_transpose = 0, 0`

`labelformat = normal | progression`

  (Default: normal)

#### Sólo para ejercicios "Id by name"

`filldir = horiz | vertic`

  Ordenar la direccion en que se llenan los botones. El valor por defecto es `vertic`.

`fillnum = INTEGER`

  Indica cuántos botones habrá en cada fila o columna.

### Bloque de Preguntas

`name = "some short name"`

  Las preguntas para id-by-name y los ejercicios chord requieren un nombre.

`music = "\staff{c'2 g' e4 e c1}"`

  La música en la oregunta. Nótese que hay un atajo de teclado en vez de:

      question {
         tempo = 160/4
         name = "Lisa gikk til skolen"
         music = "\staff\relative c'{c d e f g2 g2}"
      }

  puede escribir:

      question {
         tempo = 160/4
         name = "Lisa gikk til skolen"
         "\staff\relative c'{c d e f g2 g2}"
      }

`tempo = 130/4`

  beats per minute / notelen per beat

#### Sólo preguntas de acordes

En las lecciones que se escriben para trabajar con el ejercicio `chord` se requieren de dos variables adicionales:

`inversion`

  0 = root position, 1 = first inversion etc.

`toptone`

  1, 3, 5, 7

#### Ejercicios de dictado

Por defecto, el ejercicio de dictado mostrará la primer columna de música, y luego el usuario deberña escribir el resto. Pero si la primer columna no es adecuada, por ejemplo: sólo hay silencios en el primer tiempo, estas dos variables pueden decirle al programa qué tanta música mostrar:

`clue_end = nn/dd`

  `clue_end=1/4` mostrará toda la música en el primer tiempo.

`clue_music = MUSIC`

  Escribe la música exacta que se mostrará. Si por ejemplo desea que se muestre el primer compás en el pentagrama superior y sólo la primer nota en el pentagrama inferior.

(Use sólamente si estas variables están en la pregunta. Usar ambas están indefinidas.)

#### Ejercico de cantar acordes

Las preguntas para este ejercicio requieren que se defina la variable `key` si la armadura es cualquiera diferente de c mayor (Do Mayor) (o a minor - La menor). Ejemplo:

    question { "c''|e'|g|c" }
    question { "a'|e'|c'|a" }
    question { key="d \major" "a'|fis'|d'|d"}
    question { key="f \minor" "as'|f'|c'|f"}

### Variables Globales

Las variables globales pueden ahorrar algunas teclas.

    s = "\score\relative c'{ %s }

    question {
      # En vez de music = "\score\relative c'{ c d e f g2 g2 } :
      music = s % "c d e f g2 g"
    }

La variable global `tempo` será el tempo por defecto para la pregunta que siga a partir de esta definición. Si no se define, el valor por defecto será de 120 beats por minuto. Esto equivale a:

    tempo = 60/4

### Comentarios

Todo después del signo # se ignorará

### Gramática

Disclaimer: No conozco formas estándar de describir la gramática, como BNF. Esto es un intento de describir el formato de archivo para que la gente se inicie en escribir lecciones.

Los archivos de lecciones consisten de enunciados de asignación y bloques conteniendo enunciados de asignación.

#### Funciones

La literal `_`

  toma una cadena como su único argumento. Use esto si desea que Solfege traduzca esta cadena para usted. Ejemplo:

      description = _("Esta es una descripción corta")

Use `include`

  para incluir otro archivo en este archivo. Ejemplo:

      include(singchord-1)

#### Tipos

La literal `string`

  se escribe entre comillas usando el caracter `"`, de esta forma: `"esta es una cadena"`. Use triple comillas para cadenas que contengan retorno de carro:

      description = """<h1>Descripción larga<h1>
                     Esta lección necesita una descripción muy larga.
                     bla bla bla"""

  Si la cadena necesita contener a la comilla `"`, debe usar comillas triples:

      description = """Intente <a href="solfege:practise/melodic-interval">esto
      </a> para un ejercicio de intervalos simple."""

  NB: Todas las cadenas deben ser cadenas Unicode. Puede cambiar la codificación de un archivo usando el programa iconv:

          iconv -f  SU_CODIFICACION -t utf8 su.archivo

El `integer`

  es un entero, es un entero, es un entero...

La literal `tempotype (a falta de un mejor nombre)`

  se usa así `bpm/beatlen`. Un ejemplo:

      tempo = 120/4

  definirá el tempo a 120 beats por minuto, cada tiempo es una negra.

#### Operadores

Los operadores sólo se pueden usar en cadenas

El operador `+`

  se usa para concatenar cadenas

El operador `%`

  es semejante a lo que se usa en python, pero muy limitado. Sólo conoce del operador `%s`. Un ejemplo:

      "\staff\relative c'{%s}" % "c d e"

  se evalúa como

      "\staff\relative c'{c d e}"

#### Palabras reservadas

A ser puestas al lado derecho de las asignaciones. El intérprete actual no se quejará si usted redefine los identificadores, po lo que es mejor que ¡No lo haga!

Los identificadores `chord, dictation, id-by-name, sing-chord`

  son posibles valores para `content`

Los identificadores`horiz, vertic`

  Se usan para llenar tablas en el ejercicio id-by-name exercise

Los identificadores `normal, progression`

  `labelformat` valores.

#### Identificadores

se ajustan a expresiones regulares "[a-zA-Z]+[\w_-]*".

#### Bloques

Hay dos tipos de bloques, `header` y `question`.

    blocktype {
      CONTENIDO
    }