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 identificadoreshoriz, 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
}