@c -*- coding: utf-8; mode: texinfo; documentlanguage: es -*-
@c This file is part of extending.tely
@ignore
- Translation of GIT committish: 3c169262c8f580c0f42c09f3a61b9ae9f0d6261c
+ Translation of GIT committish: 6bbc01872dd4e9cced2524c378628d9219ac08ae
When revising a translation, copy the HEAD committish of the
version that you are working on. See TRANSLATION for details.
@end ignore
-@c \version "2.15.18"
+@c \version "2.19.2"
@node Interfaces para programadores
@chapter Interfaces para programadores
@node Bloques de código de LilyPond
@section Bloques de código de LilyPond
-@translationof Lilypond code blocks
+@translationof LilyPond code blocks
+
+@cindex Bloques de código de LilyPond
+@cindex LilyPond, bloques de código de
+@funindex #@{ @dots{} #@}
+@funindex $
+@funindex #
+
+La creación de expresiones musicales en Scheme puede ser una tarea
+tediosa porque a veces presentan muchos niveles de profundidad de
+anidamiento y el código resultante es grande. Para algunas tareas
+sencillas, esto puede evitarse utilizando bloques de código de
+LilyPond, que permiten usar la sintaxis ordinaria de LilyPond
+dentro de Scheme.
Los bloques de código de LilyPond tienen el siguiente aspecto:
@example
#@{ @var{código de LilyPond} #@}
@end example
-Se pueden usar en cualquier lugar en el que se pueda escribir código
-de Scheme: el lector de Scheme en efecto se modifica para que pueda
-incorporar bloques de código de LilyPond y pueda ocuparse de las
-expresiones de Scheme incrustadas que comienzan por @code{$} y@w{ }@code{#}.
-
-Extrae el bloque de código de LilyPond y genera una llamada al
-@code{parser} o analizador sintáctico de LilyPond, que corre en tiempo
-de ejecución para interpretar el bloque de código de LilyPond.
-Cualquier expresión de Scheme que se halle incrustada se ejecuta en el
-entorno léxico del bloque de código de LilyPond, de manera que tenemos
-acceso a las variables locales y a los parámetros de función en el
-punto en que se encuentra escrito el bloque de código de LilyPond.
+
+He aquí un ejemplo trivial:
+
+@lilypond[verbatim,quote]
+ritpp = #(define-event-function (parser location) ()
+ #{ ^"rit." \pp #}
+)
+
+{ c'4 e'4\ritpp g'2 }
+@end lilypond
+
+Los bloques de código de LilyPond se pueden usar en cualquier
+lugar en el que se pueda escribir código de Scheme. El lector de
+Scheme en efecto se modifica para que pueda incorporar bloques de
+código de LilyPond y pueda ocuparse de las expresiones de Scheme
+incrustadas que comienzan por @code{$} y@w{ }@code{#}.
+
+@cindex parser (function argument)
+@cindex location
+
+El lector extrae el bloque de código de LilyPond y genera una
+llamada en tiempo de ejecución al analizador sintáctico para que
+interprete el código de LilyPond. Las expresiones de Scheme
+incrustadas en el código de LilyPond se evalúan dentro del entorno
+lóexico del bloque de código de LilyPond, de manera que puede
+accederse a todas las variables locales y los parámetros de
+función que están disponibles en el punto en que se escribe el
+bloque de código de LilyPond. Las variables definidas en otros
+módulos de Scheme, como los módulos que contienen bloques
+@code{\header} y @code{\layout}, no están accesibles como
+variables de Scheme, es decir, precedidas de@tie{}@code{#}, pero
+se puede acceder a ellas como variables de LilyPond, es decir,
+precedidas de@tie{}@code{\}.
+
+Si @code{location} (véase @ref{Funciones de Scheme}) se refiere a una
+posición de entrada válida (como lo hace normalmente dentro de las
+funciones musicales o de Scheme), toda la música generada dentro
+del bloque de código tiene su @samp{origin} establecido a
+@code{location}.
Un bloque de código de LilyPond puede contener cualquier cosa que
podríamos utilizar en la parte derecha de una asignación. Además, un
de LilyPond (@code{#@{}@dots{}@code{#@}}) acceso al analizador
sintáctico.
+@item @code{location}
+@tab tiene que ser literalmente @code{location} para ofrecer acceso al
+objeto de situación de la entrada, que se usa para ofrecer
+menssajes de error con nombres de archivo y números de línea.
+
@item @code{@var{argN}}
@tab @var{n}-ésimo argumento
@item @code{@var{typeN?}}
@tab un @emph{predicado de tipo} de Scheme para el que @code{@var{argN}}
-debe devolver @code{#t}. Algunos de estos predicados se reconocen de
-forma especial por parte del analizador, véase más abajo. También
-existe una forma especial @code{(@emph{predicate?} @emph{default})}
-para especificar argumentos opcionales. Si el argumento actual no
-está presente cuando se ll ama a la función, el valor predeterminado se
-emplea en sustitución. Los valores predeterminados se evalúan en
-tiempo de definición (¡incluyendo los bloques de código de LilyPond!),
-de manera que se necesitamos un valor por omisión calculado en tiempo
-de ejecución, debemos escribir en su lugar un valor especial que
-podamos reconocer fácilmente. Si escribimos el predicado entre
-paréntesis pero no lo seguimos por el valor predeterminado, se usa
-@code{#f} como valor por omisión. Los valores por omisión no se
-verifican con @emph{predicate?} en tiempo de definición ni en tiempo
-de ejecución: es nuestra responsabilidad tratar con los valores que
-especifiquemos. Los valores por omisión que son expresiones musicales
-se copian mientras se establece @code{origin} al parámetro
-@code{location}.
+debe devolver @code{#t}.
+
+También existe una forma especial @code{(@emph{predicate?}
+@emph{default})} para especificar argumentos opcionales. Si el
+argumento actual no está presente cuando se ll ama a la función, el
+valor predeterminado se emplea en sustitución. Los valores
+predeterminados se evalúan en tiempo de definición (¡incluyendo los
+bloques de código de LilyPond!), de manera que se necesitamos un valor
+por omisión calculado en tiempo de ejecución, debemos escribir en su
+lugar un valor especial que podamos reconocer fácilmente. Si
+escribimos el predicado entre paréntesis pero no lo seguimos por el
+valor predeterminado, se usa @code{#f} como valor por omisión. Los
+valores por omisión no se verifican con @emph{predicate?} en tiempo de
+definición ni en tiempo de ejecución: es nuestra responsabilidad
+tratar con los valores que especifiquemos. Los valores por omisión
+que son expresiones musicales se copian mientras se establece
+@code{origin} al parámetro @code{location}.
@item @code{@var{cuerpo}}
@tab una secuencia de formas de Scheme que se evalúan ordenadamente; la
@end multitable
@noindent
-Ciertos predicados de tipo se manejan de forma especial por parte del
-analizador sintáctico ya que de otro modo éste no es capaz de
-reconocer los argumentos eficientemente. Actualmente son
-@code{ly:pitch?} y @code{ly:duration?}.
-
-La idoneidad de lpos argumentos para el resto de los predicados viene
-determinada mediante llamadas reales al predicado después de que
-LilyPond ya las ha convertido en una expresión de Scheme. Como
-consecuencia, el argumento se puede especificar en la sintaxis de
-Scheme si se desea (precedido de @code{#} o como resultado de haber
-llamado a una función de Scheme), pero LilyPond también convierte
-algunas construcciones de LilyPond en Scheme antes de hacer
-efectivamente la comprobación del predicado sobre ellas. Actualmente
-se encuentran entre ellas la música, los post-eventos, las cadenas
-simples (entrecomilladas o no), los números, los elementos de marcado
-y de listas de marcado, score (partitura), book (libro), bookpart
-(parte de libro), las definiciones de contexto y los bloques de
-definición de salida.
+La idoneidad de los argumentos para los predicados viene determinada
+mediante llamadas reales al predicado después de que LilyPond ya las
+ha convertido en una expresión de Scheme. Como consecuencia, el
+argumento se puede especificar en la sintaxis de Scheme si se desea
+(precedido de @code{#} o como resultado de haber llamado a una función
+de Scheme), pero LilyPond también convierte algunas construcciones de
+LilyPond en Scheme antes de hacer efectivamente la comprobación del
+predicado sobre ellas. Actualmente se encuentran entre ellas la
+música, los post-eventos, las cadenas simples (entrecomilladas o no),
+los números, los elementos de marcado y de listas de marcado, score
+(partitura), book (libro), bookpart (parte de libro), las definiciones
+de contexto y los bloques de definición de salida.
Para ciertos tipos de expresión (como la mayor parte de la música que
no está encerrada entre llaves) LilyPond necesita más allá de la
considerase un argumento opcional mediante la evaluación de su
predicado, LilyPond no podría recuperarse después de decidir que la
expresión no se corresponde con el parámetro. Así, ciertas formas de
-música necesitan ir encerradas entre llaves para que LilyPond pueda
-aceptarlas. Existen también otras ambigüedades que LilyPond resuelve
-mediante la comprobación con funciones de predicado: ¿es @samp{-3} un
-post-evento de digitación o un nnúmero negativo? ¿Es @code{"a" 4} en
-el modo de letra una cadena seguida por un número, o un evento de
-letra con la duración @code{4}? LilyPond lo decide preguntándole a
-los predicados. Ello significa que un debemos evitar los
-predicados permisivos como @code{scheme?} si tenemos en mente
-un uso particular en vez de una función de uso general.
+música necesitan ir encerradas entre llaves para poder considerarlas
+como aceptables bajo algunas circunstancias. LilyPond resuelve
+algunas otras ambigüedades mediante la comprobación con funciones de
+predicado: ¿es @samp{-3} un post-evento de digitación o un número
+negativo? ¿Es @code{"a" 4} en el modo de letra una cadena seguida por
+un número, o un evento de letra con la duración @code{4}? LilyPond
+prueba el predicado del argumento sobre diversas interpretaciones
+sucesivas hasta que lo consigue, con un orden diseñado para minimizar
+las interpretaciones poco consistentes y la lectura por adelantado.
+
+Por ejemplo, un predicado que acepta tanto expresiones musicales como
+alturas consideraría que @code{c''} es una altura en lugar de una
+expresión musical. Las duraciones o post-eventos que siguieran
+inmediatamente podrían no funcionar con dicha interpretación. Así
+pues, es mejor evitar los predicados excesivamente permisivos como
+@code{scheme?} cuando la aplicación requeriría tipos de argumento más
+específicos.
Para ver una lista de los predicados de tipo disponibles, consulte
@ruser{Predicados de tipo predefinidos}.
(parser location)
()
(ly:set-option 'point-and-click #f))
-...
+@dots{}
\noApuntarYPulsar % desactivar la función de apuntar y pulsar
@end example
@item
Como un post-evento, que comienza explícitamente con un indicador de
dirección (a elegir entre @code{-}, @code{^} @w{y @code{_}}).
-Observe que se puede aceptar la devolución de un
-post-evento por parte de las funciones musicales que se llaman como
-música normal, lo que lleva a un resultado aproximadamente equivalente
-a
-@example
-s 1*0-\fun
-@end example
En este caso, no podemos usar una expresión musical @emph{abierta}
como último argumento, que terminaría en una expresión musical
(parser location principio-final)
(pair?)
#@{
- \once \override Beam #'positions = #principio-final
+ \once \override Beam.positions = #principio-final
#@})
\relative c' @{
(parser location beg end)
(number? number?)
#{
- \once \override Beam #'positions = #(cons beg end)
+ \once \override Beam.positions = #(cons beg end)
#})
\relative c' {
}
@end lilypond
+@funindex \temporary
+@cindex sobreescrituras temporales
+@cindex temporales, sobreescrituras
+@cindex propiedades, recuperar valor anterior
+
+Las propiedades se mantienen conceptualmente utilizando una pila
+por cada propiedad, por cada grob y por cada contexto. Las
+funciones musicales pueden requerir la sobreescritura de una o
+varias propiedades durante el tiempo de duración de la función,
+restaurándolas a sus valores previos antes de salir. Sin embargo,
+las sobreescrituras normales extraen y descartan la cima de la
+pila de propiedades actual antes de introducir un valor en ella,
+de manera que el valor anterior de la propiedad se pierde cuando
+se sobreescribe. Si se quiere preservar el valor anterior, hay
+que preceder la instrucción @code{\override} con la palabra clave
+@code{\temporary}, así:
+
+@example
+\temporary \override @dots{}
+@end example
+
+El uso de @code{\temporary} hace que se borre la propiedad
+(normalmente fijada a un cierto valor) @code{pop-first} de la
+sobreescritura, de forma que el valor anterior no se extrae de la
+pila de propiedades antes de poner en ella el valor nuevo. Cuando
+una instrucción @code{\revert} posterior extrae el avlor
+sobreescrito temporalmente, volverá a emerger el valor anterior.
+
+En otras palabras, una llamada a @code{\temporary \override} y a
+continuación otra a @code{\revert} sobre la misma propiedad, tiene
+un valor neto que es nulo. De forma similar, la combinación en
+secuencia de @code{\temporary} y @code{\undo} sobre la misma
+música que contiene las sobreescrituras, tiene un efecto neto
+nulo.
+
+He aquí un ejemplo de una función musical que utiliza lo expuesto
+anteriormente. El uso de @code{\temporary} asegura que los
+valores de las propiedades @code{cross-staff} y @code{style} se
+restauran a la salida a los valores que tenían cuando se llamó a
+la función @code{crossStaff}. Sin @code{\temporary}, a la salida
+se habrían fijado los valores predeterminados.
+
+@example
+crossStaff =
+#(define-music-function (parser location notes) (ly:music?)
+ (_i "Create cross-staff stems")
+ #@{
+ \temporary \override Stem.cross-staff = #cross-staff-connect
+ \temporary \override Flag.style = #'no-flag
+ #notes
+ \revert Stem.cross-staff
+ \revert Flag.style
+#@})
+@end example
+
@node Matemáticas dentro de las funciones
@subsection Matemáticas dentro de las funciones
(parser location mag)
(number?)
#{
- \override Stem #'length = #(* 7.0 mag)
- \override NoteHead #'font-size =
+ \override Stem.length = #(* 7.0 mag)
+ \override NoteHead.font-size =
#(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
#})
AltOff = {
- \revert Stem #'length
- \revert NoteHead #'font-size
+ \revert Stem.length
+ \revert NoteHead.font-size
}
\relative c' {
(parser location mag music)
(number? ly:music?)
#{
- \override Stem #'length = #(* 7.0 mag)
- \override NoteHead #'font-size =
+ \override Stem.length = #(* 7.0 mag)
+ \override NoteHead.font-size =
#(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
#music
- \revert Stem #'length
- \revert NoteHead #'font-size
+ \revert Stem.length
+ \revert NoteHead.font-size
#})
\relative c' {
(parser location)
()
(if (eq? #t (ly:get-option 'display-bar-numbers))
- #@{ \once \override Score.BarNumber #'break-visibility = ##f #@}
+ #@{ \once \override Score.BarNumber.break-visibility = ##f #@}
#@{#@}))
@end example
@translationof Markup construction in Scheme
@cindex marcado, definir instrucciones de
+@funindex \displayScheme
-El macro @code{markup} construye expresiones de marcado en Scheme,
-proporcionando una sintaxis similar a la de LilyPond. Por ejemplo:
+Las expresiones de marcado se representan internamente en Scheme
+usando el macro @code{markup}:
@example
-(markup #:column (#:line (#:bold #:italic "hola" #:raise 0.4 "mundo")
- #:larger #:line ("fulano" "fulanito" "menganito")))
+(markup @var{expr})
+@end example
+
+Para ver una expresión de marcado en su forma de Scheme, utilice
+la instrucción @code{\displayScheme}:
+
+@example
+\displayScheme
+\markup @{
+ \column @{
+ \line @{ \bold \italic "hola" \raise #0.4 "mundo" @}
+ \larger \line @{ fulano fulanito menganito @}
+ @}
+@}
@end example
@noindent
-equivale a:
+La compilación del código anterior envía a la consola lo
+siguiente:
+
@example
-#@{ \markup \column @{ \line @{ \bold \italic "hola" \raise #0.4 "mundo" @}
- \larger \line @{ fulano fulanito menganito @} @} #@}
+(markup
+ #:line
+ (#:column
+ (#:line
+ (#:bold (#:italic "hola") #:raise 0.4 "mundo")
+ #:larger
+ (#:line
+ (#:simple "fulano" #:simple "fulanito" #:simple "menganito")))))
@end example
+Para evitar que el marcado se imprima en la página, use
+@w{@samp{\void \displayScheme @var{marcado}}}. Asimismo, como
+ocurre con la instrucción @code{\displayMusic}, la salida de
+@code{\displayScheme} se puede guardar en un archivo externo.
+Véase @ref{Presentación de las expresiones musicales}.
+
@noindent
Este ejemplo muestra las principales reglas de traducción entre la
sintaxis del marcado normal de LilyPond y la sintaxis del marcado de
@multitable @columnfractions .3 .3
@item @b{LilyPond} @tab @b{Scheme}
@item @code{\markup marcado1} @tab @code{(markup marcado1)}
-@item @code{\markup @{ marcado1 marcado2 ... @}} @tab
- @code{(markup marcado1 marcado2 ... )}
+@item @code{\markup @{ marcado1 marcado2 @dots{} @}} @tab
+ @code{(markup marcado1 marcado2 @dots{} )}
@item @code{\instruccion} @tab @code{#:instruccion}
@item @code{\variable} @tab @code{variable}
-@item @code{\center-column @{ ... @}} @tab @code{#:center-column ( ... )}
+@item @code{\center-column @{ @dots{} @}} @tab
+ @code{#:center-column ( @dots{} )}
@item @code{cadena} @tab @code{"cadena"}
@item @code{#argumento-de-scheme} @tab @code{argumento-de-scheme}
@end multitable
Scheme @code{define-markup-command}, en el nivel sintáctico superior.
@lisp
-(define-markup-command (@var{nombre-de-la-instruccion} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
- (@var{tipo-de-arg1?} @var{tipo-de-arg2?} ...)
+(define-markup-command (@var{nombre-de-la-instruccion} @var{layout} @var{props} @var{arg1} @var{arg2} @dots{})
+ (@var{tipo-de-arg1?} @var{tipo-de-arg2?} @dots{})
[ #:properties ((@var{propiedad1} @var{valor-predeterminado1})
- ...) ]
- ..command body..)
+ @dots{}) ]
+ @dots{}command body@dots{})
@end lisp
Los argumentos son
Scheme para los argumentos antecedentes de las funciones de marcado
que toman un marcado como su último argumento.
+@funindex \markup
+@cindex markup macro
+@funindex interpret-markup
+Las instrucciones de marcado tienen un ciclo de vida más bien
+complejo. El cuerpo de la definición de una instrucción de marcado es
+responsable de la conversión de los argumentos de la instrucción de
+marcado en una expresión de sello que se devuelve. Muy a menudo esto
+se lleva a cabo llamando a la función @code{interpret-markup} sobre
+una expresión de marcado, pasándole los argumentos @var{layout} y
+@var{props}. Por lo general, estos argumentos se conocen solamente en
+una fase muy tardía de la composición tipográfica. Las expresiones de
+marcado ya tienen sus componentes ensamblados dentro de expresiones de
+marcado cuando se expanden las instrucciones @code{\markup} (dentro de
+una expresión de LilyPond) o la macro @code{markup} (dentro de
+Scheme). La evaluación y la comprobación de tipos de los argumentos
+de la instrucción de marcado tiene lugar en el momento en que se
+interpretan @code{\markup} o @code{markup}.
+
+Pero la conversión real de expresiones de marcado en expresiones de
+sello mediante la ejecución de los cuerpos de función de marcado solo
+tienen lugar cuando se llama a @code{interpret-markup} sobre una
+expresión de marcado.
+
@node Acerca de las propiedades
@unnumberedsubsubsec Acerca de las propiedades
@translationof On properties
\override #'(box-padding . 0.6) \box @{ #text @}#@}))
@end lisp
-or, equivalently
+o, de forma equivalente,
@lisp
#(define-markup-command (double-box layout props text) (markup?)
(number-pair?)
#:category graphic
#:properties ((thickness 1))
- "...documentación..."
+ "@dots{}documentación@dots{}"
(let ((th (* (ly:output-def-lookup layout 'line-thickness)
thickness))
(x (car dest))
(define-markup-command (draw-double-line layout props dest)
(number-pair?)
#:properties ((thickness 1))
- "...documentación..."
+ "@dots{}documentación@dots{}"
(let ((th (* (ly:output-def-lookup layout 'line-thickness)
thickness))
(x (car dest))
(number-pair?)
#:properties ((thickness 1)
(line-gap 0.6))
- "...documentación..."
- ...
+ "@dots{}documentación@dots{}"
+ @dots{}
@end lisp
Finalmente, se añade el código para trazar las dos líneas. Se usan
@subsection Definición de nuevas instrucciones de lista de marcado
@translationof New markup list command definition
+@funindex define-markup-list-command
+@funindex interpret-markup-list
+
Las instrucciones de listas de marcado se definen con el macro de
Scheme @code{define-markup-list-command}, que es similar al macro
@code{define-markup-command} descrito en @ref{Definición de una
(@rinternals{ApplyOutputEvent}). Su sintaxis es
@example
-\applyOutput @var{contexto} @var{proc}
+\applyOutput @var{Contexto} @var{proc}
@end example
@noindent
donde @code{@var{proc}} es una función de Scheme que toma tres argumentos.
Al interpretarse, la función @code{@var{proc}} se llama para cada objeto de
-presentación que se encuentra en el contexto @code{@var{contexto}}
+presentación que se encuentra en el contexto @code{@var{Contexto}}
en el tiempo actual, con los siguientes argumentos:
@itemize
}
@end lilypond
+Para que @var{función} se interprete en los niveles de @code{Score} o de @code{Staff}
+utilice estas formas:
+
+@example
+\applyOutput #'Score #@var{función}
+\applyOutput #'Staff #@var{función}
+@end example
+
@node Funciones de callback
@section Funciones de callback
p. ej.:
@example
-\override Stem #'thickness = #2.0
+\override Stem.thickness = #2.0
@end example
Las propiedades pueden fijarse también a un procedimiento de Scheme,
@lilypond[fragment,verbatim,quote,relative=2]
-\override Stem #'thickness = #(lambda (grob)
+\override Stem.thickness = #(lambda (grob)
(if (= UP (ly:grob-property grob 'direction))
2.0
7.0))
@translationof Inline Scheme code
La principal desventaja de @code{\tweak} es su inflexibilidad
-sintáctica. Por ejemplo, lo siguiente produce un error de sintaxis.
+sintáctica. Por ejemplo, lo siguiente produce un error de sintaxis (o
+más bien: así lo hacía en algún momento del pasado):
@example
-F = \tweak #'font-size #-3 -\flageolet
+F = \tweak font-size #-3 -\flageolet
\relative c'' @{
c4^\F c4_\F
(ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
\relative c'' {
- \override Tie #'after-line-breaking =
+ \override Tie.after-line-breaking =
#my-callback
c1 ~ \break
- c2 ~ c
+ c2 ~ 2
}
@end lilypond
@example
\overrideProperty
-#"Score.NonMusicalPaperColumn" % Nombre del grob
-#'line-break-system-details % Nombre de la propiedad
-#'((next-padding . 20)) % Valor
+Score.NonMusicalPaperColumn % Nombre del grob
+ . line-break-system-details % Nombre de la propiedad
+ . next-padding % Nombre de la subpropiedad, opcional
+ #20 % Valor
@end example
Observe, sin embargo, que @code{\override}, aplicado a
projects / lilypond.git / blobdiff