@c -*- coding: utf-8; mode: texinfo; documentlanguage: es -*-
@ignore
- Translation of GIT committish: 9c43de58d4686a5ff9bbf7149dfe0159b45dbccc
+ Translation of GIT committish: 2160b5e2145aa40ad3c48fa85e20b3853d8562db
When revising a translation, copy the HEAD committish of the
version that you are working on. For details, see the Contributors'
Guide, node Updating translation committishes..
@end ignore
-@c \version "2.12.0"
+@c \version "2.15.20"
@node Tutorial de Scheme
@appendix Tutorial de Scheme
@translationof Scheme tutorial
-@funindex #
@cindex Scheme
@cindex GUILE
@cindex Scheme, código en línea
usuarios de Windows pueden seleccionar simplemente @q{Ejecutar} del
menú Inicio e introducir @q{guile}.
-Una vez está funcionando el cajón de arena de Guile, verá un indicador
+Sin embargo, está disponible un cajón de arena de Scheme listo para
+funcionar con todo LilyPond cargado, con esta instrucción de la línea
+de órdenes:
+@example
+lilypond scheme-sandbox
+@end example
+
+@noindent
+Una vez está funcionando el cajón de arena, verá un indicador
del sistema de Guile:
@lisp
@item Números
Los números se escriben de la forma normal, @code{1} es el número
-(entero) uno, mientras que @code{-1.5} es un número en coma flotante
+(entero) uno, mientras que @w{@code{-1.5}} es un número en coma flotante
(un número no entero).
@item Cadenas
@subheading Valores de retorno
+Los procedimientos de Scheme siempre devuelven un valor de retorno,
+que es el valor de la última expresión ejecutada en el procedimiento.
+El valor de retorno puede ser cualquier valor de Scheme válido,
+incluso una estructura de datos compleja o un procedimiento.
+
A veces, el usuario quiere tener varias expresiones de Scheme dentro
de un procedimiento. Existen dos formas en que se pueden combinar
distintas expresiones. La primera es el procedimiento @code{begin},
@node Sintaxis del Scheme de LilyPond
@subsection Sintaxis del Scheme de LilyPond
@translationof LilyPond Scheme syntax
+@funindex $
+@funindex #
-En un archivo de música, los fragmentos de código de Scheme se
-escriben con el signo de almohadilla @code{#}. Así, los ejemplos
-anteriores traducidos a LilyPond son:
+El intérprete Guile forma parte de LilyPond, lo que significa que se
+puede incluir Scheme dentro de los archivos de entrada de LilyPond.
+Existen varios métodos para incluir Scheme dentro de LilyPond.
+
+La manera más sencilla es utilizar el símbolo de
+almohadilla@tie{}@code{#} antes de una expresión de Scheme.
+
+Ahora bien, el código de entrada de LilyPond se estructura en
+elementos y expresiones, de forma parecida a cómo el lenguaje humano
+se estructura en palabras y frases. LilyPond tiene un analizador
+léxico que reconoce elementos indivisibles (números literales, cadenas
+de texto, elementos de Scheme, nombres de nota, etc.), y un analizador
+sintáctico que entiende la sintaxis, la @ruser{Gramática de LilyPond}.
+Una vez que sabe que se aplica una regla sintáctica concreta, ejecuta
+las acciones asociadas con ella.
+
+El método del símbolo de almohadilla@tie{}@code{#} para incrustar
+Scheme se adapta de forma natural a este sistema. Una vez que el
+analizador léxico ve un símbolo de almohadilla, llama al lector de
+Scheme para que lea una expresión de Scheme completa (que puede ser un
+identificador, una expresión encerrada entre paréntesis, o algunas
+otras cosas). Después de que se ha leído la expresión de Scheme, se
+almacena como el valor de un elemento @code{SCM_TOKEN} de la
+gramática. Después de que el analizador sintáctico ya sabe cómo hacer
+uso de este elemento, llama a Guila para que evalúe la expresión de
+Scheme. Dado que el analizador sintáctico suele requerir un poco de
+lectura por delante por parte del analizador léxico para tomar sus
+decisiones de análisis sintáctico, esta separación de lectura y
+evaluación entre los analizadores léxico y sintáctico es justamente lo
+que se necesita para mantener sincronizadas las ejecuciones de
+expresiones de LilyPond y de Scheme. Por este motivo se debe usar el
+símbolo de almohadilla@tie{}@code{#} para llamar a Scheme siempre que
+sea posible.
+
+Otra forma de llamar al intérprete de Scheme desde lilyPond es el uso
+del símbolo de dólar@tie{}@code{$} en lugar de la almohadilla para
+introducir las expresiondes de Scheme. En este caso, LilyPond evalúa
+el código justo después de que el analizador léxico lo ha leído.
+Comprueba el tipo resultante de la expresión de Scheme y después
+selecciona un tipo de elemento (uno de los varios elementos
+@code{xxx_IDENTIFIER} dentro de la sintaxis) para él. Crea una
+@emph{copia} del valor y la usa como valor del elemento. Si el valor
+de la expresión es vacío (El valor de Guile de @code{*unspecified*}),
+no se pasa nada en absoluto al analizador sintáctico.
+
+Éste es, de hecho, el mismo mecanismo exactamente que LilyPond emplea
+cuando llamamos a cualquier variable o función musical por su nombre,
+como @code{\nombre}, con la única diferencia de que su final viene
+determinado por el analizador léxico de LilyPond sin consultar al
+lector de Scheme, y así solamente se aceptan los nombres de variable
+consistentes con el modo actual de LilyPond.
+
+La acción inmediata de @code{$} puede llevar a alguna que otra
+sorpresa, véase @ref{Variables de entrada y Scheme}. La utilización
+de @code{#} donde el analizador sintáctico lo contempla es normalmente
+preferible.
+
+Ahora echemos un vistazo a algo de código de Scheme real. Los
+procedimientos de Scheme se pueden definir dentro de los archivos de
+entrada de LilyPond:
@example
-##t ##f
-#1 #-1.5
-#"esto es una cadena"
-#"esto
-es
-una cadena"
+#(define (media a b c) (/ (+ a b c) 3))
@end example
Observe que los comentarios de LilyPond (@code{%} y @code{%@{ %@}}) no
-se pueden utilizar dentro del código de Scheme. Los comentarios en
-el Scheme de Guile se introducen como sigue:
+se pueden utilizar dentro del código de Scheme, ni siquiera dentro de
+un archivo de entrada de LilyPond, porque es el intérprete Guile, y no
+el analizador léxico de LilyPond, el que está leyendo la expresión de
+Scheme. Los comentarios en el Scheme de Guile se introducen como
+sigue:
@example
; esto es un comentario de una línea
!#
@end example
-Se pueden combinar en un mismo archivo de música varias expresiones de
-Scheme consecutivas mediante la utilización del operador @code{begin}.
-Ello permite que el número de marcas de cuadradillo se reduzca a una.
+Durante el resto de esta sección, supondremos que los datos se
+introducen en un archivo de música, por lo que añadiremos
+almohadillas@tie{}@code{#} al principio de todas las expresiones de Scheme.
+
+Todas las expresiones de Scheme del nivel jerárquico superior dentro
+de un archivo de entrada de LilyPond se pueden combinar en una sola
+expresión de Scheme mediante la utilización del operador @code{begin}:
@example
#(begin
(define menganito 1))
@end example
-Si el @code{#} va seguido de un paréntesis de apertura, @code{(}, como
-en el ejemplo anterior, el analizador sintáctico permanece dentro del
-modo de Scheme hasta que encuentra el paréntesis de cierre
-correspondiente, @code{)}, por lo que no son necesarios más símbolos
-de @code{#} para introducir una sección de Scheme.
-
-Durante el resto de esta sección, supondremos que los datos se
-introducen en un archivo de música, por lo que añadiremos almohadillas
-@code{#} en todas partes.
@node Variables de LilyPond
@subsection Variables de LilyPond
@translationof LilyPond variables
-@c TODO -- make this read right
-
-Algo similar ocurre con las variables. Después de definir una
-variable,
+Las variables de LilyPond se almacenan internamente en la forma de
+variables de Scheme. Así,
@example
doce = 12
@end example
@noindent
-las variables se pueden usar también dentro de expresiones, aquí
+equivale a
+
+@example
+#(define doce 12)
+@end example
+
+Esto significa que las variables de LilyPond están disponibles para su
+uso dentro de expresiones de Scheme. Por ejemplo, podríamos usar
@example
veintiCuatro = (* 2 doce)
@end example
@noindent
-el número 24 se almacena dentro de la variable @code{veintiCuatro}.
+lo que daría lugar a que el número 24 se almacenase dentro de la
+variable @code{veintiCuatro} de LilyPond (y de Scheme).
+
+La forma usual de referirse a las variables de LilyPond,
+@ref{Sintaxis del Scheme de LilyPond},
+
+es llamarlas usando una barra invertida, es decir
+@code{\veintiCuatro}. Dado que esto crea una copia para la mayor
+parte de los tipos internos de LilyPond, concretamente las expresiones
+musicales, las funciones musicales no sueln crear copias del material
+que ellas mismas modifican. Por este motivo, las expresiones
+musicales dadas con @code{#} no deberían, por lo general, contener
+material que no se haya creado partiendo de cero o copiado
+explícitamente en lugar de estar referenciado directamente.
@node Variables de entrada y Scheme
@subsection Variables de entrada y Scheme
traLaLa = @{ c'4 d'4 @}
\layout @{ traLaLa = 1.0 @}
@end example
+
@c
En efecto, cada archivo de entrada constituye un ámbito, y cada bloque
@code{\header}, @code{\midi} y @code{\layout} son ámbitos anidados
Tanto las variables como los ámbitos están implementados en el sistema
de módulos de GUILE. A cada ámbito se adjunta un módulo anónimo de
-Scheme. Una asignación de la forma
+Scheme. Una asignación de la forma:
@example
traLaLa = @{ c'4 d'4 @}
@end example
@noindent
-se convierte internamente en una definición de Scheme
+se convierte internamente en una definición de Scheme:
@example
(define traLaLa @var{Valor Scheme de `@code{... }'})
@end example
-Esto significa que las variables de entrada y las variables de Scheme
+Esto significa que las variables de LilyPond y las variables de Scheme
se pueden mezclar con libertad. En el ejemplo siguiente, se almacena
un fragmento de música en la variable @code{traLaLa}, y se duplica
usando Scheme. El resultado se importa dentro de un bloque
@lilypond[verbatim]
traLaLa = { c'4 d'4 }
-%% dummy action to deal with parser lookahead
-#(display "this needs to be here, sorry!")
-
#(define newLa (map ly:music-deep-copy
(list traLaLa traLaLa)))
#(define twice
@c Due to parser lookahead
-En este ejemplo, la asignación se produce después de que el analizador
-sintáctico ha verificado que no ocurre nada interesante después de
-@code{traLaLa = @{ ... @}}. Sin la sentencia muda del ejemplo
-anterior, la definición de @code{newLa} se ejecuta antes de que se
-defina @code{traLaLa}, produciendo un error de sintaxis.
+En realidad, éste es un ejemplo bastante interesante. La asignación
+solo tiene lugar después de que el analizador sintáctico se ha
+asegurado de que no sigue nada parecido a @code{\addlyrics}, de manera
+que necesita comprobar lo que viene a continuación. Lee el símbolo
+@code{#} y la expresión de Scheme siguiente @emph{sin} evaluarla, de
+forma que puede proceder a la asignación, y @emph{posteriormente}
+ejecutar el código de Scheme sin problema.
El ejemplo anterior muestra cómo @q{exportar} expresiones musicales
desde la entrada al intérprete de Scheme. Lo contrario también es
-posible. Envolviendo un valor de Scheme en la función
-@code{ly:export}, se interpreta un valor de Scheme como si hubiera
-sido introducido en la sintaxis de LilyPond. En lugar de definir
-@code{\twice}, el ejemplo anterior podría también haberse escrito como
+posible. Colocándolo después de @code{$}, un valor de Scheme se
+interpreta como si hubiera sido introducido en la sintaxis de
+LilyPond. En lugar de definir @code{\twice}, el ejemplo anterior
+podría también haberse escrito como
@example
...
-@{ #(ly:export (make-sequential-music (list newLa))) @}
+@{ $(make-sequential-music (list newLa)) @}
@end example
-El código de Scheme se evalúa tan pronto como el analizador sintáctico
-lo encuentra. Para definir código de Scheme dentro de un macro (para
-llamarse más tarde), utilice @ref{Funciones vacías}, o bien
+Podemos utilizar @code{$} con una expresión de Scheme en cualquier
+lugar en el que usaríamos @code{\@var{nombre}} después de haber
+asignado la expresión de Scheme a una variable @var{nombre}. Esta
+sustitución se produce dentro del @q{analizador léxico}, de manera que
+LilyPond no llega a darse cuenta de la diferencia.
+
+Sin embargo, existe un inconveniente, el de la medida del tiempo. Si
+hubiésemos estado usando @code{$} en vez de @code{#} para definir
+@code{newLa} en el ejemplo anterior, la siguiente definición de Scheme
+habría fracasado porque @code{traLaLa} no habría sido definida aún.
+Para ver una explicación de este problema de momento temporal, véase
+@ref{Sintaxis del Scheme de LilyPond}.
+
+En cualquier caso, la evaluación del código de Scheme se produce
+dentro del analizador sintáctico como muy tarde. Si necesitamos que
+se ejecute en un punto temporal más tardío,
+usaríamos @ref{Funciones de Scheme vacías}, o lo almacenaríamos en un
+macro:
@example
#(define (nopc)
@knownissues
No es posible mezclar variables de Scheme y de LilyPond con la opción
-@code{--safe}.
-
-
+@option{--safe}.
@node Propiedades de los objetos
@subsection Propiedades de los objetos
@translationof Object properties
-Esta sintaxis se usará con mucha frecuencia, pues muchos de los trucos
-de presentación consisten en asignar valores (de Scheme) a variables
-internas, por ejemplo
+Las propiedades de los objetos se almacenan en LilyPond en forma de
+cadenas de listas-A, que son listas de listas-A. Las propiedades se
+establecen añadiendo valores al principio de la lista de propiedades.
+Las propiedades se leen extrayendo valores de las listas-A.
+
+El establecimiento de un valor nuevo para una propiedad requiere la
+asignación de un valor a la lista-A con una clave y un valor. La
+sintaxis de LilyPond para hacer esto es la siguiente:
@example
\override Stem #'thickness = #2.6
@end example
-Esta instrucción ajusta el aspecto de las plicas. El valor @code{2.6}
-se pone dentro de la variable @code{thickness} de un objeto
-@code{Stem}. @code{thickness} se mide a partir del grosor de las
-líneas del pentagrama, y así estas plicas serán @code{2.6} veces el
-grosor de las líneas del pentagrama. Esto hace que las plicas sean
-casi el doble de gruesas de lo normal. Para distinguir entre las
-variables que se definen en los archivos de entrada (como
-@code{veintiCuatro} en el ejemplo anterior) y las variables de los
-objetos internos, llamaremos a las últimas @q{propiedades} y a las
-primeras @q{variables.} Así, el objeto plica tiene una propiedad
-@code{thickness} (grosor), mientras que @code{veintiCuatro} es una
-variable.
+Esta instrucción ajusta el aspecto de las plicas. Se añade una
+entrada de lista-A @code{'(thickness . 2.6)} a la lista de propiedades
+de un objeto @code{Stem}. @code{thickness} se mide a partir del
+grosor de las líneas del pentagrama, y así estas plicas serán
+@code{2.6} veces el grosor de las líneas del pentagrama. Esto hace
+que las plicas sean casi el doble de gruesas de lo normal. Para
+distinguir entre las variables que se definen en los archivos de
+entrada (como @code{veintiCuatro} en el ejemplo anterior) y las
+variables de los objetos internos, llamaremos a las últimas
+@q{propiedades} y a las primeras @q{variables.} Así, el objeto plica
+tiene una propiedad @code{thickness} (grosor), mientras que
+@code{veintiCuatro} es una variable.
@cindex propiedades frente a variables
@cindex variables frente a propiedades
@subheading Desplazamientos
-Los desplazamientos bidimensionales (coordenadas X e Y) así como los
-tamaños de los objetos (intervalos con un punto izquierdo y otro
-derecho) se introducen como @code{parejas}. Una pareja@footnote{En la
-terminología de Scheme, la pareja se llama @code{cons}, y sus dos
-elementos se llaman @code{car} y @code{cdr} respectivamente.} se
-introduce como @code{(primero . segundo)} y, como los símbolos, se deben
-preceder de un apóstrofo:
+Los desplazamientos bidimensionales (coordenadas X e Y) se almacenan
+como @code{parejas}. El @code{car} del desplazamiento es la
+coordenada X, y el @code{cdr} es la coordenada Y.
@example
\override TextScript #'extra-offset = #'(1 . 2)
@end example
-Esto asigna la pareja (1, 2) a la propiedad @code{extra-offset} del
-objeto TextScript. Estos números se miden en espacios de pentagrama,
-y así esta instrucción mueve el objeto un espacio de pentagrama a la
-derecha, y dos espacios hacia arriba.
+Esto asigna la pareja @code{(1 . 2)} a la propiedad
+@code{extra-offset} del objeto TextScript. Estos números se miden en
+espacios de pentagrama, y así esta instrucción mueve el objeto un
+espacio de pentagrama a la derecha, y dos espacios hacia arriba.
+
+Los procedimientos para trabajar con desplazamientos están en
+@file{scm/lily-library.scm}.
@subheading Dimensiones
-HACER @c todo -- write something about extents
+Las parejas se usan también para almacenar intervalos, que representan
+un rango de números desde el mínimo (el @code{car}) hasta el máximo
+(el @code{cdr}). Los intervalos se usan para almacenar las
+dimensiones en X y en Y de los objetos imprimibles. Para dimensiones
+en X, el @code{car} es la coordenada X de la parte izquierda, y el
+@code{cdr} es la coordenada X de la parte derecha. Para las
+dimensiones en Y, el @code{car} es la coordenada inferior, y el
+@code{cdr} es la coordenada superior.
+
+Los procedimientos para trabajar con intervalos están en
+@file{scm/lily-library.scm}. Se deben usar estos procedimientos
+siempre que sea posible, para asegurar la consistencia del código.
@subheading Listas-A de propiedades
-HACER @c todo -- write something about property alists
+Una lista-A de propiedades es una estructura de datos de LilyPond que
+es una lista-A cuyas claves son propiedades y cuyos valores son
+expresiones de Scheme que dan el valor deseado de la propiedad.
+
+Las propiedades de LilyPond son símbolos de Scheme, como por ejemplo
+@code{'thickness}.
@subheading Cadenas de listas-A
-HACER @c todo -- write something about alist chains
+Una cadena de listas-A es una lista que contiene listas-A de
+propiedades.
+
+El conjunto de todas las propiedades que se aplican a un grob se
+almacena por lo general como una cadena de listas-A. Para poder
+encontrar el valor de una propiedad determinada que debería tener un
+grob, se busca por todas las listas-A de la cadena, una a una,
+tratando de encontrar una entrada que contenga la clave de la
+propiedad. Se devuelve la primera entrada de lista-A que se
+encuentre, y el valor es el valor de la propiedad.
+
+El procedimiento de Scheme @code{chain-assoc-get} se usa normalmente
+para obtener los valores de propiedades.
@node Representación interna de la música
@subsection Representación interna de la música
@translationof Internal music representation
+Internamente, la música se representa como una lista de Scheme. La
+lista contiene varios elementos que afectan a la salida impresa. El
+análisis sintáctico es el proceso de convertir la música de la
+representación de entrada de LilyPond a la representación interna de
+Scheme.
+
Cuando se analiza una expresión musical, se convierte en un conjunto
de objetos musicales de Scheme. La propiedad definitoria de un objeto
-musical es que ocupa un tiempo. El tiempo es un número racional que
-mide la longitud de una pieza de música en redondas.
+musical es que ocupa un tiempo. El tiempo que ocupa se llama
+@emph{duración}. Las duraciones se expresan como un número racional
+que mide la longitud del objeto musical en redondas.
Un objeto musical tiene tres clases de tipos:
@itemize
lilypond archivo.ly >salida.txt
@end example
-Con la aplicación de un poco de formateo, la información anterior es
-fácil de leer,
+Con un poco de magia combinada de LilyPond y Scheme, podemos realmente
+hacer que LilyPond dirija solamente esta salida a su propio archivo:
+
+@example
+@{
+ $(with-output-to-file "display.txt"
+ (lambda () #@{ \displayMusic @{ c'4\f @} #@}))
+@}
+@end example
+
+
+Un poco de reformateo hace a la información anterior más fácil de
+leer:
@example
(make-music 'SequentialMusic
cualquier información adicional (en este caso, un evento
@code{AbsoluteDynamicEvent} con una propiedad @code{"f"} de texto.
+@funindex{\void}
+
+@code{\displayMusic} devuelve la música que imprime en la consola, y
+por ello se interpretará al tiempo que se imprime en la consola. Para
+evitar la interpretación, escriba @code{\void} antes de
+@code{\displayMusic}.
@node Propiedades musicales
@subsection Propiedades musicales
@translationof Music properties
+@c TODO -- make sure we delineate between @emph{music} properties,
+@c @emph{context} properties, and @emph{layout} properties. These
+@c are potentially confusing.
+
El objeto @code{NoteEvent} es el primer objeto de la propiedad
@code{'elements} de @code{someNote}.
Así pues, en nuestra función, tenemos que clonar esta expresión (de
forma que tengamos dos notas para construir la secuencia), añadir
-@code{SlurEvents} a la propiedad @code{'elements} de cada una de
+@code{SlurEvent} a la propiedad @code{'elements} de cada una de
ellas, y por último hacer una secuencia @code{SequentialMusic} con los
dos @code{EventChords}.
@lilypond[quote,verbatim,ragged-right]
padText = #(define-music-function (parser location padding) (number?)
#{
- \once \override TextScript #'padding = #$padding
+ \once \override TextScript #'padding = #padding
#})
\relative c''' {
(number? string?)
#{
\once \override Score.MetronomeMark #'padding = $padding
- \tempo \markup { \bold $tempotext }
+ \tempo \markup { \bold #tempotext }
#})
\relative c'' {