1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: es -*-
2 @c This file is part of extending.tely
4 Translation of GIT committish: 708aa920d682cf9aa3ed647cd129afd8509760f4
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
12 @node Interfaces para programadores
13 @chapter Interfaces para programadores
14 @translationof Interfaces for programmers
16 Se pueden realizar trucos avanzados mediante el uso de Scheme.
17 Si no está familiarizado con Scheme, le conviene leer nuestro
18 tutorial de Scheme, @ref{Tutorial de Scheme}.
22 * Bloques de código de LilyPond::
23 * Funciones de Scheme::
24 * Funciones musicales::
25 * Funciones de eventos::
26 * Funciones de marcado::
27 * Contextos para programadores::
28 * Funciones de callback::
32 @node Bloques de código de LilyPond
33 @section Bloques de código de LilyPond
34 @translationof LilyPond code blocks
36 @cindex Bloques de código de LilyPond
37 @cindex LilyPond, bloques de código de
38 @funindex #@{ @dots{} #@}
42 La creación de expresiones musicales en Scheme puede ser una
43 tarea tediosa porque a veces presentan muchos niveles de
44 profundidad de anidamiento y el código resultante es grande.
45 Para algunas tareas sencillas, esto puede evitarse utilizando
46 bloques de código de LilyPond, que permiten usar la sintaxis
47 ordinaria de LilyPond dentro de Scheme.
49 Los bloques de código de LilyPond tienen el siguiente aspecto:
51 #@{ @var{código de LilyPond} #@}
54 He aquí un ejemplo trivial:
56 @lilypond[verbatim,quote]
57 ritpp = #(define-event-function () ()
64 Los bloques de código de LilyPond se pueden usar en cualquier
65 lugar en el que se pueda escribir código de Scheme. El lector de
66 Scheme en efecto se modifica para que pueda incorporar bloques de
67 código de LilyPond y pueda ocuparse de las expresiones de Scheme
68 incrustadas que comienzan por @code{$} y@w{ }@code{#}.
70 El lector extrae el bloque de código de LilyPond y genera una
71 llamada en tiempo de ejecución al analizador sintáctico para que
72 interprete el código de LilyPond. Las expresiones de Scheme
73 incrustadas en el código de LilyPond se evalúan dentro del
74 entorno lóexico del bloque de código de LilyPond, de manera que
75 puede accederse a todas las variables locales y los parámetros de
76 función que están disponibles en el punto en que se escribe el
77 bloque de código de LilyPond. Las variables definidas en otros
78 módulos de Scheme, como los módulos que contienen bloques
79 @code{\header} y @code{\layout}, no están accesibles como
80 variables de Scheme, es decir, precedidas de@tie{}@code{#}, pero
81 se puede acceder a ellas como variables de LilyPond, es decir,
82 precedidas de@tie{}@code{\}.
84 Toda la música generada dentro del bloque de código tiene su
85 @samp{origin} establecido a la localización actual del puntero de
88 Un bloque de código de LilyPond puede contener cualquier cosa que
89 podríamos utilizar en la parte derecha de una asignación.
90 Además, un bloque de LilyPond vacío corresponde a una expresión
91 musical vacía, y un bloque de LilyPond que contiene varios
92 eventos musicales se convierte en una expresión de música
95 @node Funciones de Scheme
96 @section Funciones de Scheme
97 @translationof Scheme functions
98 @cindex Scheme, funciones de (sintaxis de LilyPond)
100 Las @emph{funciones de Scheme} son procedimientos de Scheme que
101 pueden crear expresiones de Scheme a partir de código de entrada
102 escrito en la sintaxis de LilyPond. Se pueden llamar desde
103 prácticamente cualquier lugar en el que se permita el uso de
104 @code{#} para la especificación de un valor en sintaxis de
105 Scheme. Mientras que Scheme tiene funciones propias, este
106 capítulo se ocupa de las funciones @emph{sintácticas}, funciones
107 que reciben argumentos especificados en la sintaxis de LilyPond.
110 * Definición de funciones de Scheme::
111 * Uso de las funciones de Scheme::
112 * Funciones de Scheme vacías::
115 @node Definición de funciones de Scheme
116 @subsection Definición de funciones de Scheme
117 @translationof Scheme function definitions
118 @funindex define-scheme-function
120 La forma general de la definición de una función de Scheme es:
124 #(define-scheme-function
125 (@var{arg1} @var{arg2} @dots{})
126 (@var{tipo1?} @var{tipo2?} @dots{})
133 @multitable @columnfractions .33 .66
134 @item @code{@var{argN}}
135 @tab @var{n}-ésimo argumento.
137 @item @code{@var{typeN?}}
138 @tab Un @emph{predicado de tipo} de Scheme para el que @code{@var{argN}}
139 debe devolver @code{#t}. También existe una forma especial
140 @code{(@emph{predicate?} @emph{default})} para especificar
141 argumentos opcionales. Si el argumento actual no está presente
142 cuando se ll ama a la función, el valor predeterminado se emplea
143 en sustitución. Los valores predeterminados se evalúan en tiempo
144 de definición (¡incluyendo los bloques de código de LilyPond!),
145 de manera que se necesitamos un valor por omisión calculado en
146 tiempo de ejecución, debemos escribir en su lugar un valor
147 especial que podamos reconocer fácilmente. Si escribimos el
148 predicado entre paréntesis pero no lo seguimos por el valor
149 predeterminado, se usa @code{#f} como valor por omisión. Los
150 valores por omisión no se verifican con @emph{predicate?} en
151 tiempo de definición ni en tiempo de ejecución: es nuestra
152 responsabilidad tratar con los valores que especifiquemos. Los
153 valores por omisión que son expresiones musicales se copian
154 mientras se establece @code{origin} a la ubicación actual del
157 @item @code{@var{cuerpo}}
158 @tab una secuencia de formas de Scheme que se evalúan ordenadamente; la
159 última forma de la secuencia se usa como el valor de retorno de
160 la función de Scheme. Puede contener bloques de código de
161 LilyPond encerrados entre llaves con almohadillas
162 (@tie{}@w{@code{#@{@dots{}#@}}}@tie{}), como se describe en
163 @ref{Bloques de código de LilyPond}. Dentro de los bloques de
164 código de LilyPond, use el símbolo @code{#} para hacer referencia
165 a argumentos de función (p.ej. @samp{#arg1}) o para iniciar una
166 expresión en línea de Scheme que contenga argumentos de función
167 (p.ej. @w{@samp{#(cons arg1 arg2)}}). Donde las expresiones de
168 Scheme normales que usan @code{#} no funcionan, podríamos
169 necesitar volver a expresiones de Scheme inmediatas que usan
170 @code{$}, como por ejemplo @samp{$music}.
172 Si nuestra función devuelve una expresión musical, recibe un
173 valor @code{origin} útil.
177 La idoneidad de los argumentos para los predicados viene
178 determinada mediante llamadas reales al predicado después de que
179 LilyPond ya las ha convertido en una expresión de Scheme. Como
180 consecuencia, el argumento se puede especificar en la sintaxis de
181 Scheme si se desea (precedido de @code{#} o como resultado de
182 haber llamado a una función de Scheme), pero LilyPond también
183 convierte algunas construcciones de LilyPond en Scheme antes de
184 hacer efectivamente la comprobación del predicado sobre ellas.
185 Actualmente se encuentran entre ellas la música, los
186 post-eventos, las cadenas simples (entrecomilladas o no), los
187 números, los elementos de marcado y de listas de marcado, score
188 (partitura), book (libro), bookpart (parte de libro), las
189 definiciones de contexto y los bloques de definición de salida.
191 LilyPond resuelve algunas ambigüedades mediante la comprobación
192 con funciones de predicado: ¿es @samp{-3} un post-evento de
193 digitación o un número negativo? ¿Es @code{"a" 4} en el modo de
194 letra una cadena seguida por un número, o un evento de letra con
195 la duración @code{4}? LilyPond prueba el predicado del argumento
196 sobre diversas interpretaciones sucesivas hasta que lo consigue,
197 con un orden diseñado para minimizar las interpretaciones poco
198 consistentes y la lectura por adelantado.
200 Por ejemplo, un predicado que acepta tanto expresiones musicales
201 como alturas consideraría que @code{c''} es una altura en lugar
202 de una expresión musical. Las duraciones o post-eventos que
203 siguen inmediatamente, cambian dicha interpretación. Es mejor
204 evitar los predicados excesivamente permisivos como
205 @code{scheme?} cuando la aplicación requeriría tipos de argumento
208 Para ver una lista de los predicados de tipo disponibles,
209 consulte @ruser{Predicados de tipo predefinidos}.
213 Referencia de la notación:
214 @ruser{Predicados de tipo predefinidos}.
217 @file{lily/music-scheme.cc},
222 @node Uso de las funciones de Scheme
223 @subsection Uso de las funciones de Scheme
224 @translationof Scheme function usage
226 Las funciones de Scheme se pueden llamar casi desde cualquier
227 lugar en que puede escribirse una expresión de Scheme que
228 comience con la almohadilla@tie{}@code{#}. Llamamos a una
229 función de Scheme escribiendo su nombre precedido de la barra
230 invertida@tie{}@code{\}, y seguido por sus argumentos. Una vez
231 que un argumento opcional no corresponde a ningún argumento,
232 LilyPond se salta este argumento y todos los que le siguen,
233 sustituyéndolos por su valor por omisión especificado, y
234 @q{recupera} el argumento que no correspondía al lugar del
235 siguiente argumento obligatorio. Dado que el argumento
236 recuperado necesita ir a algún lugar, los argumentos opcionales
237 no se consideran realmente opcionales a no ser que vayan seguidos
238 de un argumento obligatorio.
240 Existe una excepción: si escribimos @code{\default} en el lugar
241 de un argumento opcional, este argumento y todos los argumentos
242 opcionales que le siguen se saltan y se sustituyen por sus
243 valores predeterminados. Esto funciona incluso si no sigue
244 ningún argumento obligatorio porque @code{\default} no necesita
245 recuperarse. Las instrucciones @code{mark} y @code{key} hacen
246 uso de este truco para ofrecer su comportamiento predeterminado
247 cuando van seguidas solamente por @code{\default}.
249 Aparte de los lugares en que se requiere un valor de Scheme hay
250 ciertos sitios en que se aceptan expresiones de almohadilla
251 @code{#} y se evalúan por sus efectos secundarios, pero por lo
252 demás se ignoran. Son, mayormente, los lugares en que también
253 sería aceptable colocar una asignación.
255 Dado que no es buena idea devolver valores que puedan
256 malinterpretarse en algún contexto, debería usar funciones de
257 Scheme normales solo para los casos en que siempre se devuelve un
258 valor útil, y usar funciones de Scheme vacías (@pxref{Funciones
259 de Scheme vacías}) en caso contrario.
261 Por conveniencia, las funciones de Scheme también se pueden
262 llamar directamente desde Scheme, puenteando al analizador
263 sintáctico de LilyPond. Su nombre puede utilizarse como el
264 nombre de una función corriente. La comprobación de tipo de los
265 argumentos y el salto de los argumentos opcionales tiene lugar de
266 la misma forma que cuando se llama desde dentro de LilyPond,
267 tomando el valor de Scheme @code{*unspecified*} el papel de la
268 palabra reservada @code{\default} para saltar explícitamente
269 argumentos opcionales.
271 @node Funciones de Scheme vacías
272 @subsection Funciones de Scheme vacías
273 @translationof Void scheme functions
274 @funindex define-void-function
277 En ocasiones, un procedimiento se ejecuta con el objeto de llevar
278 a cabo alguna acción más que para devolver un valor. Algunos
279 lenguajes de programación (como C y Scheme) usan las funciones
280 para los dos conceptos y se limitan a descartar el valor devuelto
281 (usualmente haciendo que cualquier expresión pueda actuar como
282 instrucción, ignorando el resultado devuelto). Esto puede
283 parecer inteligente pero es propenso a errores: casi todos los
284 compiladores de C de hoy en día emiten advertencias cuando se
285 descarta una expresión no vacía. Para muchas funciones que
286 ejecutan una acción, los estándares de Scheme declaran que el
287 valor de retorno sea no especificado. Guile, el intérprete de
288 Scheme de LilyPond, tiene un valor único @code{*unspecified*} que
289 en tales casos devuelve de forma usual (como cuando se usa
290 directamente @code{set!} sobre una variable), pero
291 desgraciadamente no de forma consistente.
293 Definir una función de LilyPond con @code{define-void-function}
294 asegura que se devuelve este valor especial, el único valor que
295 satisface el predicado @code{void?}.
299 #(define-void-function
302 (ly:set-option 'point-and-click #f))
304 \noApuntarYPulsar % desactivar la función de apuntar y pulsar
307 Si queremos evaluar una expresión sólo por su efecto colateral y
308 no queremos que se interprete ningún valor que pueda devolver,
309 podemos hacerlo anteponiendo el prefijo @code{\void}:
312 \void #(hashq-set! some-table some-key some-value)
315 De esta forma podemos asegurar que LilyPond no asignará ningún
316 significado al valor devuelto, independientemente de dónde lo
317 encuentre. También funciona para funciones musicales como
318 @code{\displayMusic}.
320 @node Funciones musicales
321 @section Funciones musicales
322 @translationof Music functions
324 @cindex funciones musicales
326 Las @emph{funciones musicales} son procedimientos de Scheme que
327 pueden crear automáticamente expresiones musicales, y se pueden
328 usar para simplificar enormemente el archivo de entrada.
331 * Definiciones de funciones musicales::
332 * Uso de las funciones musicales::
333 * Funciones de sustitución sencillas::
334 * Funciones de sustitución intermedias::
335 * Matemáticas dentro de las funciones::
336 * Funciones sin argumentos::
337 * Funciones musicales vacías::
341 @node Definiciones de funciones musicales
342 @subsection Definiciones de funciones musicales
343 @translationof Music function definitions
344 @cindex definición de funciones musicales
345 @funindex define-music-function
347 La forma general para definir funciones musicales es:
351 #(define-music-function
352 (@var{arg1} @var{arg2} @dots{})
353 (@var{tipo1?} @var{tipo2?} @dots{})
358 de forma bastante análoga a
359 @ref{Definición de funciones de Scheme}. Lo más probable es que
360 el @var{cuerpo} sea un
361 @ref{Bloques de código de LilyPond,bloque de código de LilyPond}.
363 Para ver una lista de los predicados de tipo disponibles,
364 consulte @ruser{Predicados de tipo predefinidos}.
368 Referencia de la notación:
369 @ruser{Predicados de tipo predefinidos}.
372 @file{lily/music-scheme.cc},
377 @node Uso de las funciones musicales
378 @subsection Uso de las funciones musicales
379 @translationof Music function usage
381 Una @q{función musical} debe devolver una expresión que se
382 corresponda con el predicado @code{ly:music?}. Esto hace que las
383 llamadas a funciones musicales sean aproopiadas como argumentos
384 del tipo @code{ly:music?} para otra llamada a una función
387 Si se usa una llamada a función musical dentro de otros
388 contextos, el contexto puede aplicar restricciones semánticas
393 En el nivel superior dentro de una expresión musical no se acepta
397 Cuando una función musical (a diferencia de una función de
398 evento) devuelve una expresión del tipo post-event, LilyPond
399 requiere uno de los indicadores de dirección con nombre
400 (@code{-}, @code{^}, @w{y @code{_}}) para poder integrar
401 adecuadamente el post-evento producido por la llamada a la
402 función musical dentro de la expresión circundante.
405 Como componente de un acorde. La expresión devuelta debe ser del
406 tipo @code{rhythmic-event}, probablemente un @code{NoteEvent}.
410 Se pueden aplicar funciones @q{polimórficas}, como @code{\tweak},
411 a los post-eventos, componentes de acordes y expresiones
412 musicales del nivel superior.
414 @node Funciones de sustitución sencillas
415 @subsection Funciones de sustitución sencillas
416 @translationof Simple substitution functions
418 Una función de sustitución sencilla es una función musical cuya
419 expresión musical de salida está escrita en código de LilyPond y
420 contiene argumentos de la función en la expresión de salida.
421 Están descritas en @ruser{Ejemplos de funciones de sustitución}.
424 @node Funciones de sustitución intermedias
425 @subsection Funciones de sustitución intermedias
426 @translationof Intermediate substitution functions
428 Las funciones de sustitución intermedias contienen una mezcla de
429 código de Scheme y de LilyPond dentro de la expresión musical que
432 Algunas instrucciones @code{\override} requieren un argumento que
433 consiste en una pareja de números (llamada una @emph{célula cons}
436 La pareja se puede pasar directamente dentro de la función
437 musical, usando una variable @code{pair?}:
441 #(define-music-function
445 \once \override Beam.positions = #principio-final
449 \barraManual #'(3 . 6) c8 d e f
453 De forma alternativa, los números que componen la pareja se
454 pueden pasar como argumentos separados, y el código de Scheme que
455 se ha usado para crear la pareja se puede incluir dentro de la
458 @lilypond[quote,verbatim,ragged-right]
460 #(define-music-function
464 \once \override Beam.positions = #(cons beg end)
468 \manualBeam #3 #6 c8 d e f
473 @cindex sobreescrituras temporales
474 @cindex temporales, sobreescrituras
475 @cindex propiedades, recuperar valor anterior
477 Las propiedades se mantienen conceptualmente utilizando una pila
478 por cada propiedad, por cada grob y por cada contexto. Las
479 funciones musicales pueden requerir la sobreescritura de una o
480 varias propiedades durante el tiempo de duración de la función,
481 restaurándolas a sus valores previos antes de salir. Sin
482 embargo, las sobreescrituras normales extraen y descartan la cima
483 de la pila de propiedades actual antes de introducir un valor en
484 ella, de manera que el valor anterior de la propiedad se pierde
485 cuando se sobreescribe. Si se quiere preservar el valor
486 anterior, hay que preceder la instrucción @code{\override} con la
487 palabra clave @code{\temporary}, así:
490 \temporary \override @dots{}
493 El uso de @code{\temporary} hace que se borre la propiedad
494 (normalmente fijada a un cierto valor) @code{pop-first} de la
495 sobreescritura, de forma que el valor anterior no se extrae de la
496 pila de propiedades antes de poner en ella el valor nuevo.
497 Cuando una instrucción @code{\revert} posterior extrae el valor
498 sobreescrito temporalmente, volverá a emerger el valor anterior.
500 En otras palabras, una llamada a @code{\temporary \override} y a
501 continuación otra a @code{\revert} sobre la misma propiedad,
502 tiene un valor neto que es nulo. De forma similar, la
503 combinación en secuencia de @code{\temporary} y @code{\undo}
504 sobre la misma música que contiene las sobreescrituras, tiene un
507 He aquí un ejemplo de una función musical que utiliza lo expuesto
508 anteriormente. El uso de @code{\temporary} asegura que los
509 valores de las propiedades @code{cross-staff} y @code{style} se
510 restauran a la salida a los valores que tenían cuando se llamó a
511 la función @code{crossStaff}. Sin @code{\temporary}, a la salida
512 se habrían fijado los valores predeterminados.
516 #(define-music-function (notes) (ly:music?)
517 (_i "Create cross-staff stems")
519 \temporary \override Stem.cross-staff = #cross-staff-connect
520 \temporary \override Flag.style = #'no-flag
522 \revert Stem.cross-staff
528 @node Matemáticas dentro de las funciones
529 @subsection Matemáticas dentro de las funciones
530 @translationof Mathematics in functions
532 Las funciones musicales pueden contar con programación de Scheme
533 además de la simple sustitución:
535 @lilypond[quote,verbatim,ragged-right]
537 #(define-music-function
541 \override Stem.length = #(* 7.0 mag)
542 \override NoteHead.font-size =
543 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
548 \revert NoteHead.font-size
553 \AltOn #1.5 c c \AltOff c2
558 Este ejemplo se puede reescribir de forma que pase expresiones
561 @lilypond[quote,verbatim,ragged-right]
563 #(define-music-function
567 \override Stem.length = #(* 7.0 mag)
568 \override NoteHead.font-size =
569 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
572 \revert NoteHead.font-size
576 c'2 \withAlt #0.5 { c4 c }
577 \withAlt #1.5 { c c } c2
582 @node Funciones sin argumentos
583 @subsection Funciones sin argumentos
584 @translationof Functions without arguments
586 En casi todos los casos, una función sin argumentos se debe
587 escribir con una variable:
590 dolce = \markup@{ \italic \bold dolce @}
593 Sin embargo, en raras ocasiones puede ser de utilidad crear una
594 función musical sin argumentos:
597 mostrarNumeroDeCompas =
598 #(define-music-function
601 (if (eq? #t (ly:get-option 'display-bar-numbers))
602 #@{ \once \override Score.BarNumber.break-visibility = ##f #@}
606 Para la impresión real de los números de compás donde se llama a
607 esta función, invoque a @command{lilypond} con
610 lilypond -d display-bar-numbers ARCHIVO.ly
614 @node Funciones musicales vacías
615 @subsection Funciones musicales vacías
616 @translationof Void music functions
618 Una función musical debe devolver una expresión musical. Si
619 quiere ejecutar una función exclusivamente por sus efectos
620 secundarios, debería usar @code{define-void-function}. Pero
621 puede haber casos en los que a veces queremos producir una
622 expresión musical, y a veces no (como en el ejemplo anterior).
623 Devolver una expresión musical @code{void} (vacía) por medio de
624 @code{#@{ #@}} lo hace posible.
627 @node Funciones de eventos
628 @section Funciones de eventos
629 @translationof Event functions
630 @funindex define-event-function
631 @cindex event functions
633 Para usar una función musical en el lugar de un evento, tenemos
634 que escribir un indicador de dirección antes de ella. Pero a
635 veces, ello hace que se pierda la correspondencia con la sintaxis
636 de las construcciones que queremos sustituir. Por ejemplo, si
637 queremos escribir instrucciones de matiz dinámico, éstos se
638 adjuntan habitualmente sin indicador de dirección, como
639 @code{c'\pp}. He aquí una forma de escribir indicaciones
640 dinámicas arbitrarias:
642 @lilypond[quote,verbatim,ragged-right]
643 dyn=#(define-event-function (arg) (markup?)
644 (make-dynamic-script arg))
645 \relative { c'\dyn pfsss }
648 Podríamos hacer lo mismo usando una función musical, pero
649 entonces tendríamos que escribir siempre un indicador de
650 dirección antes de llamarla, como @code{@w{c-\dyn pfsss}}.
653 @node Funciones de marcado
654 @section Funciones de marcado
655 @translationof Markup functions
657 Los elementos de marcado están implementados como funciones de
658 Scheme especiales que producen un objeto @code{Stencil} dada una
663 * Construcción de elementos de marcado en Scheme::
664 * Cómo funcionan internamente los elementos de marcado::
665 * Definición de una instrucción de marcado nueva::
666 * Definición de nuevas instrucciones de lista de marcado::
669 @node Construcción de elementos de marcado en Scheme
670 @subsection Construcción de elementos de marcado en Scheme
671 @translationof Markup construction in Scheme
673 @cindex marcado, definir instrucciones de
674 @funindex \displayScheme
676 Las expresiones de marcado se representan internamente en Scheme
677 usando el macro @code{markup}:
683 Para ver una expresión de marcado en su forma de Scheme, utilice
684 la instrucción @code{\displayScheme}:
690 \line @{ \bold \italic "hola" \raise #0.4 "mundo" @}
691 \larger \line @{ fulano fulanito menganito @}
697 La compilación del código anterior envía a la consola lo
705 (#:bold (#:italic "hola") #:raise 0.4 "mundo")
708 (#:simple "fulano" #:simple "fulanito" #:simple "menganito")))))
711 Para evitar que el marcado se imprima en la página, use
712 @w{@samp{\void \displayScheme @var{marcado}}}. Asimismo, como
713 ocurre con la instrucción @code{\displayMusic}, la salida de
714 @code{\displayScheme} se puede guardar en un archivo externo.
715 Véase @ref{Presentación de las expresiones musicales}.
718 Este ejemplo muestra las principales reglas de traducción entre
719 la sintaxis del marcado normal de LilyPond y la sintaxis del
720 marcado de Scheme. La utilización de @code{#@{ @dots{} #@}} para
721 escribir en la sintaxis de LilyPond será con frecuencia lo más
722 conveniente, pero explicamos cómo usar la macro @code{markup}
723 para obtener una solución sólo con Scheme.
726 @multitable @columnfractions .3 .3
727 @item @b{LilyPond} @tab @b{Scheme}
728 @item @code{\markup marcado1} @tab @code{(markup marcado1)}
729 @item @code{\markup @{ marcado1 marcado2 @dots{} @}} @tab
730 @code{(markup marcado1 marcado2 @dots{} )}
731 @item @code{\instruccion} @tab @code{#:instruccion}
732 @item @code{\variable} @tab @code{variable}
733 @item @code{\center-column @{ @dots{} @}} @tab
734 @code{#:center-column ( @dots{} )}
735 @item @code{cadena} @tab @code{"cadena"}
736 @item @code{#argumento-de-scheme} @tab @code{argumento-de-scheme}
740 Todo el lenguaje Scheme está accesible dentro del macro
741 @code{markup}. Por ejemplo, podemos usar llamadas a funciones
742 dentro de @code{markup} para así manipular cadenas de caracteres.
743 Esto es útil si se están definiendo instrucciones de marcado
744 nuevas (véase @ref{Definición de una instrucción de marcado
750 El argumento markup-list de instrucciones como @code{#:line},
751 @code{#:center} y @code{#:column} no puede ser una variable ni el
752 resultado de la llamada a una función.
755 (markup #:line (funcion-que-devuelve-marcados))
759 no es válido. Hay que usar las funciones
760 @code{make-line-markup}, @code{make-center-markup} o
761 @code{make-column-markup} en su lugar:
764 (markup (make-line-markup (funcion-que-devuelve-marcados)))
768 @node Cómo funcionan internamente los elementos de marcado
769 @subsection Cómo funcionan internamente los elementos de marcado
770 @translationof How markups work internally
772 En un elemento de marcado como
775 \raise #0.5 "ejemplo de texto"
779 @code{\raise} se representa en realidad por medio de la función
780 @code{raise-markup}. La expresión de marcado se almacena como
783 (list raise-markup 0.5 (list simple-markup "ejemplo de texto"))
786 Cuando el marcado se convierte en objetos imprimibles (Stencils o
787 sellos), se llama la función @code{raise-markup} como
791 @var{\objeto de marcado}
792 @var{lista de listas asociativas de propiedades}
794 @var{el marcado "ejemplo de texto"})
797 Primero la función @code{raise-markup} crea el sello para la
798 cadena @code{ejemplo de texto}, y después eleva el sello Stencil
799 en 0.5 espacios de pentagrama. Este es un ejemplo bastante
800 simple; en el resto de la sección podrán verse ejemplos más
801 complejos, así como en @file{scm/define-markup-commands.scm}.
804 @node Definición de una instrucción de marcado nueva
805 @subsection Definición de una instrucción de marcado nueva
806 @translationof New markup command definition
808 Esta sección trata sobre la definición de nuevas instrucciones de
813 * Sintaxis de la definición de instrucciones de marcado::
814 * Acerca de las propiedades::
815 * Un ejemplo completo::
816 * Adaptación de instrucciones incorporadas::
819 @node Sintaxis de la definición de instrucciones de marcado
820 @unnumberedsubsubsec Sintaxis de la definición de instrucciones de marcado
821 @translationof Markup command definition syntax
823 Se pueden definir instrucciones de marcado nuevas usando el macro
824 de Scheme @code{define-markup-command}, en el nivel sintáctico
828 (define-markup-command (@var{nombre-de-la-instruccion} @var{layout} @var{props} @var{arg1} @var{arg2} @dots{})
829 (@var{tipo-de-arg1?} @var{tipo-de-arg2?} @dots{})
830 [ #:properties ((@var{propiedad1} @var{valor-predeterminado1})
832 @dots{}command body@dots{})
838 @item @var{nombre-de-la-instruccion}
839 nombre de la instrucción de marcado
841 la definición de @q{layout} (disposición).
843 una lista de listas asociativas, que contienen todas las propiedades
846 argumento @var{i}-ésimo de la instrucción
847 @item @var{tipo-de-argi?}
848 predicado de tipo para el argumento @var{i}-ésimo
851 Si la instrucción utiliza propiedades de los argumentos
852 @code{props}, se puede usar la palabra clave @code{#:properties}
853 para especificar qué propiedades se usan, así como sus valores
856 Los argumentos se distinguen según su tipo:
858 @item un marcado, que corresponde al predicado de tipo @code{markup?};
859 @item una lista de marcados, que corresponde al predicado de tipo
861 @item cualquier otro objeto de Scheme, que corresponde a predicados de tipo como
862 @code{list?}, @code{number?}, @code{boolean?}, etc.
865 No existe ninguna limitación en el orden de los argumentos
866 (después de los argumentos estándar @code{layout} y
867 @code{props}). Sin embargo, las funciones de marcado que toman
868 un elemento de marcado como su último argumento son un poco
869 especiales porque podemos aplicarlas a una lista de marcados y el
870 resultado es una lista de marcados donde la función de marcado
871 (con los argumentos antecedentes especificados) se ha aplicado a
872 todos los elementos de la lista de marcados original.
874 Dado que la replicación de los argumentos precedentes para
875 aplicar una función de marcado a una lista de marcados es poco
876 costosa principalmente por los argumentos de Scheme, se evitan
877 las caídas de rendimiento simplemente mediante la utilización de
878 argumentos de Scheme para los argumentos antecedentes de las
879 funciones de marcado que toman un marcado como su último
884 @funindex interpret-markup
885 Las instrucciones de marcado tienen un ciclo de vida más bien
886 complejo. El cuerpo de la definición de una instrucción de
887 marcado es responsable de la conversión de los argumentos de la
888 instrucción de marcado en una expresión de sello que se devuelve.
889 Muy a menudo esto se lleva a cabo llamando a la función
890 @code{interpret-markup} sobre una expresión de marcado, pasándole
891 los argumentos @var{layout} y @var{props}. Por lo general, estos
892 argumentos se conocen solamente en una fase muy tardía de la
893 composición tipográfica. Las expresiones de marcado ya tienen
894 sus componentes ensamblados dentro de expresiones de marcado
895 cuando se expanden las instrucciones @code{\markup} (dentro de
896 una expresión de LilyPond) o la macro @code{markup} (dentro de
897 Scheme). La evaluación y la comprobación de tipos de los
898 argumentos de la instrucción de marcado tiene lugar en el momento
899 en que se interpretan @code{\markup} o @code{markup}.
901 Pero la conversión real de expresiones de marcado en expresiones
902 de sello mediante la ejecución de los cuerpos de función de
903 marcado solo tienen lugar cuando se llama a
904 @code{interpret-markup} sobre una expresión de marcado.
906 @node Acerca de las propiedades
907 @unnumberedsubsubsec Acerca de las propiedades
908 @translationof On properties
910 Los argumentos @code{layout} y @code{props} de las instrucciones
911 de marcado traen a escena un contexto para la interpretación del
912 marcado: tamaño de la tipografía, grueso de línea, etc.
914 El argumento @code{layout} permite el acceso a las propiedades
915 definidas en los bloques @code{paper}, usando la función
916 @code{ly:output-def-lookup}. Por ejemplo, el grueso de línea (el
917 mismo que el que se usa en las partituras) se lee usando:
920 (ly:output-def-lookup layout 'line-width)
923 El argumento @code{props} hace accesibles algunas propiedades a
924 las instrucciones de marcado. Por ejemplo, cuando se interpreta
925 el marcado del título de un libro, todas las variables definidas
926 dentro del bloque @code{\header} se añaden automáticamente a
927 @code{props}, de manera que el marcado del título del libro puede
928 acceder al título del libro, el autor, etc. También es una forma
929 de configurar el comportamiento de una instrucción de marcado:
930 por ejemplo, cuando una instrucción utiliza tamaños de tipografía
931 durante el procesado, el tamaño se lee de @code{props} en vez de
932 tener un argumento @code{font-size}. El que llama a una
933 instrucción de marcado puede cambiar el valor de la propiedad del
934 tamaño de la tipografía con el objeto de modificar el
935 comportamiento. Utilice la palabra clave @code{#:properties} de
936 @code{define-markup-command} para especificar qué propiedades se
937 deben leer a partir de los argumentos de @code{props}.
939 El ejemplo de la sección siguiente ilustra cómo acceder y
940 sobreescribir las propiedades de una instrucción de marcado.
943 @node Un ejemplo completo
944 @unnumberedsubsubsec Un ejemplo completo
945 @translationof A complete example
947 El ejemplo siguiente define una instrucción de marcado para
948 trazar un rectángulo doble alrededor de un fragmento de texto.
950 En primer lugar, necesitamos construir un resultado aproximado
951 utilizando marcados. Una consulta a @ruser{Instrucciones de
952 marcado de texto} nos muestra que es útil la instrucción
955 @lilypond[quote,verbatim,ragged-right]
956 \markup \box \box HELLO
959 Ahora, consideramos que es preferible tener más separación entre
960 el texto y los rectángulos. Según la documentación de
961 @code{\box}, esta instrucción usa una propiedad
962 @code{box-padding}, cuyo valor predeterminado es 0.2. La
963 documentación también menciona cómo sobreescribir este valor:
965 @lilypond[quote,verbatim,ragged-right]
966 \markup \box \override #'(box-padding . 0.6) \box A
969 Después, el relleno o separación entre los dos rectángulos nos
970 parece muy pequeño, así que lo vamos a sobreescribir también:
972 @lilypond[quote,verbatim,ragged-right]
973 \markup \override #'(box-padding . 0.4) \box
974 \override #'(box-padding . 0.6) \box A
977 Repetir esta extensa instrucción de marcado una y otra vez sería
978 un quebradero de cabeza. Aquí es donde se necesita una
979 instrucción de marcado. Así pues, escribimos una instrucción de
980 marcado @code{double-box}, que toma un argumento (el texto).
981 Dibuja los dos rectángulos y añade una separación.
984 #(define-markup-command (double-box layout props text) (markup?)
985 "Trazar un rectángulo doble rodeando el texto."
986 (interpret-markup layout props
987 #@{\markup \override #'(box-padding . 0.4) \box
988 \override #'(box-padding . 0.6) \box @{ #text @}#@}))
991 o, de forma equivalente,
994 #(define-markup-command (double-box layout props text) (markup?)
995 "Trazar un rectángulo doble rodeando el texto."
996 (interpret-markup layout props
997 (markup #:override '(box-padding . 0.4) #:box
998 #:override '(box-padding . 0.6) #:box text)))
1001 @code{text} es el nombre del argumento de la instrucción, y
1002 @code{markup?} es el tipo: lo identifica como un elemento de
1003 marcado. La función @code{interpret-markup} se usa en casi todas
1004 las instrucciones de marcado: construye un sello, usando
1005 @code{layout}, @code{props}, y un elemento de marcado. En el
1006 segundo caso, la marca se construye usando el macro de Scheme
1007 @code{markup}, véase @ref{Construcción de elementos de marcado en
1008 Scheme}. La transformación de una expresión @code{\markup} en
1009 una expresión de marcado de Scheme es directa.
1011 La instrucción nueva se puede usar como sigue:
1014 \markup \double-box A
1017 Sería bueno hacer que la instrucción @code{double-box} fuera
1018 personalizable: aquí, los valores de relleno @code{box-padding}
1019 son fijos, y no se pueden cambiar por parte del usuario. Además,
1020 sería mejor distinguir la separación entre los dos rectángulos,
1021 del relleno entre el rectángulo interno y el texto. Así pues,
1022 introducimos una nueva propiedad, @code{inter-box-padding}, para
1023 el relleno entre los rectángulos. El @code{box-padding} se usará
1024 para el relleno interno. Ahora el código nuevo es como se ve a
1028 #(define-markup-command (double-box layout props text) (markup?)
1029 #:properties ((inter-box-padding 0.4)
1031 "Trazar un rectángulo doble rodeando el texto."
1032 (interpret-markup layout props
1033 #@{\markup \override #`(box-padding . ,inter-box-padding) \box
1034 \override #`(box-padding . ,box-padding) \box
1038 De nuevo, la versión equivalente que utiliza la macro de marcado
1042 #(define-markup-command (double-box layout props text) (markup?)
1043 #:properties ((inter-box-padding 0.4)
1045 "Trazar un rectángulo doble rodeando el texto."
1046 (interpret-markup layout props
1047 (markup #:override `(box-padding . ,inter-box-padding) #:box
1048 #:override `(box-padding . ,box-padding) #:box text)))
1051 Aquí, la palabra clave @code{#:properties} se usa de manera que
1052 las propiedades @code{inter-box-padding} y @code{box-padding} se
1053 leen a partir del argumento @code{props}, y se les proporcionan
1054 unos valores predeterminados si las propiedades no están
1057 Después estos valores se usan para sobreescribir las propiedades
1058 @code{box-padding} usadas por las dos instrucciones @code{\box}.
1059 Observe el apóstrofo invertido y la coma en el argumento de
1060 @code{\override}: nos permiten introducir un valor de variable
1061 dentro de una expresión literal.
1063 Ahora, la instrucción se puede usar dentro de un elemento de
1064 marcado, y el relleno de los rectángulos se puede personalizar:
1066 @lilypond[quote,verbatim,ragged-right]
1067 #(define-markup-command (double-box layout props text) (markup?)
1068 #:properties ((inter-box-padding 0.4)
1070 "Draw a double box around text."
1071 (interpret-markup layout props
1072 #{\markup \override #`(box-padding . ,inter-box-padding) \box
1073 \override #`(box-padding . ,box-padding) \box
1076 \markup \double-box A
1077 \markup \override #'(inter-box-padding . 0.8) \double-box A
1078 \markup \override #'(box-padding . 1.0) \double-box A
1082 @node Adaptación de instrucciones incorporadas
1083 @unnumberedsubsubsec Adaptación de instrucciones incorporadas
1084 @translationof Adapting builtin commands
1086 Una buena manera de comenzar a escribir una instrucción de
1087 marcado nueva, es seguir el ejemplo de otra instrucción ya
1088 incorporada. Casi todas las instrucciones de marcado que están
1089 incorporadas en LilyPond se pueden encontrar en el archivo
1090 @file{scm/define-markup-commands.scm}.
1092 Por ejemplo, querríamos adaptar la instrucción @code{\draw-line},
1093 para que trace una línea doble. La instrucción @code{\draw-line}
1094 está definida como sigue (se han suprimido los comentarios de
1098 (define-markup-command (draw-line layout props dest)
1101 #:properties ((thickness 1))
1102 "@dots{}documentación@dots{}"
1103 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
1107 (make-line-stencil th 0 0 x y)))
1110 Para definir una instrucción nueva basada en otra existente,
1111 copie la definición y cámbiele el nombre. La palabra clave
1112 @code{#:category} se puede eliminar sin miedo, pues sólo se
1113 utiliza para generar documentación de LilyPond, y no tiene
1114 ninguna utilidad para las instrucciones de marcado definidas por
1118 (define-markup-command (draw-double-line layout props dest)
1120 #:properties ((thickness 1))
1121 "@dots{}documentación@dots{}"
1122 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
1126 (make-line-stencil th 0 0 x y)))
1129 A continuación se añade una propiedad para establecer la
1130 separación entre las dos líneas, llamada @code{line-gap}, con un
1131 valor predeterminado de p.ej. 0.6:
1134 (define-markup-command (draw-double-line layout props dest)
1136 #:properties ((thickness 1)
1138 "@dots{}documentación@dots{}"
1142 Finalmente, se añade el código para trazar las dos líneas. Se
1143 usan dos llamadas a @code{make-line-stencil} para trazar las
1144 líneas, y los sellos resultantes se combinan usando
1145 @code{ly:stencil-add}:
1147 @lilypond[quote,verbatim,ragged-right]
1148 #(define-markup-command (my-draw-line layout props dest)
1150 #:properties ((thickness 1)
1153 (let* ((th (* (ly:output-def-lookup layout 'line-thickness)
1157 (w (/ line-gap 2.0))
1158 (x (cond ((= dx 0) w)
1160 (else (/ w (sqrt (+ 1 (* (/ dx dy) (/ dx dy))))))))
1161 (y (* (if (< (* dx dy) 0) 1 -1)
1164 (else (/ w (sqrt (+ 1 (* (/ dy dx) (/ dy dx))))))))))
1165 (ly:stencil-add (make-line-stencil th x y (+ dx x) (+ dy y))
1166 (make-line-stencil th (- x) (- y) (- dx x) (- dy y)))))
1168 \markup \my-draw-line #'(4 . 3)
1169 \markup \override #'(line-gap . 1.2) \my-draw-line #'(4 . 3)
1173 @node Definición de nuevas instrucciones de lista de marcado
1174 @subsection Definición de nuevas instrucciones de lista de marcado
1175 @translationof New markup list command definition
1177 @funindex define-markup-list-command
1178 @funindex interpret-markup-list
1180 Las instrucciones de listas de marcado se definen con el macro de
1181 Scheme @code{define-markup-list-command}, que es similar al macro
1182 @code{define-markup-command} descrito en @ref{Definición de una
1183 instrucción de marcado nueva}, excepto que donde éste devuelve un
1184 sello único, aquél devuelve una lista de sellos.
1186 En el siguiente ejemplo se define una instrucción de lista de
1187 marcado @code{\paragraph}, que devuelve una lista de líneas
1188 justificadas, estando la primera de ellas sangrada. La anchura
1189 del sangrado se toma del argumento @code{props}.
1192 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1193 #:properties ((par-indent 2))
1194 (interpret-markup-list layout props
1195 #@{\markuplist \justified-lines @{ \hspace #par-indent #args @} #@}))
1199 La versión que usa solamente Scheme es más compleja:
1201 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1202 #:properties ((par-indent 2))
1203 (interpret-markup-list layout props
1204 (make-justified-lines-markup-list (cons (make-hspace-markup par-indent)
1208 Aparte de los argumentos usuales @code{layout} y @code{props}, la
1209 instrucción de lista de marcados @code{paragraph} toma un
1210 argumento de lista de marcados, llamado @code{args}. El
1211 predicado para listas de marcados es @code{markup-list?}.
1213 En primer lugar, la función toma el ancho del sangrado, una
1214 propiedad llamada aquí @code{par-indent}, de la lista de
1215 propiedades @code{props}. Si no se encuentra la propiedad, el
1216 valor predeterminado es @code{2}. Después, se hace una lista de
1217 líneas justificadas usando la instrucción incorporada de lista de
1218 marcados @code{\justified-lines}, que está relacionada con la
1219 función @code{make-justified-lines-markup-list}. Se añade un
1220 espacio horizontal al principio usando @code{\hspace} (o la
1221 función @code{make-hspace-markup}). Finalmente, la lista de
1222 marcados se interpreta usando la función
1223 @code{interpret-markup-list}.
1225 Esta nueva instrucción de lista de marcados se puede usar como
1231 El arte de la tipografía musical se llama \italic @{grabado (en plancha).@}
1232 El término deriva del proceso tradicional de impresión de música.
1233 hace sólo algunas décadas, las partituras se hacían cortando y estampando
1234 la música en una plancha de zinc o lata en una imagen invertida.
1236 \override-lines #'(par-indent . 4) \paragraph @{
1237 La plancha se tenía que entintar, y las depresiones causadas por los cortes
1238 y estampados retienen la tinta. Se formaba una imagen presionando el papel
1239 contra la plancha. El estampado y cortado se hacía completamente
1246 @node Contextos para programadores
1247 @section Contextos para programadores
1248 @translationof Contexts for programmers
1251 * Evaluación de contextos::
1252 * Ejecutar una función sobre todos los objetos de la presentación::
1255 @node Evaluación de contextos
1256 @subsection Evaluación de contextos
1257 @translationof Context evaluation
1259 @cindex código, llamadas durante la interpretación
1260 @funindex \applyContext
1261 @funindex make-apply-context
1262 @funindex ly:context-property
1263 @funindex ly:context-set-property!
1264 @funindex ly:context-grob-definition
1265 @funindex ly:assoc-get
1266 @funindex ly:context-pushpop-property
1268 Se pueden modificar los contextos durante la interpretación con
1269 código de Scheme. Dentro de un bloque de código de LilyPond, la
1270 sintaxis para esto es:
1273 \applyContext @var{función}
1276 En código de Scheme, la sintaxis es:
1279 (make-apply-context @var{function})
1282 @code{@var{función}} debe ser una función de Scheme que toma un
1283 único argumento, que es el contexto al que aplicarla. La función
1284 puede acceder a, así como sobreescribir u establecer propiedades
1285 de grobs s y propiedades de contextos. Cualquier acción tomada
1286 por la función que dependa del estado del contexto, está limitada
1287 al estado del contexto @emph{en el momento de llamar a la
1288 función}. Asimismo, los cambios efectuados por una llamada a
1289 @code{\applyContext} permanecen en efecto hasta que se modifican
1290 de nuevo directamente, o se revierten, incluso si han cambiado las
1291 condiciones iniciales sobre las que dependen.
1293 Las siguientes funciones de Scheme son útiles cuando se utiliza
1294 @code{\applyContext}:
1297 @item ly:context-property
1298 recuperar el valor de una propiedad de contexto
1300 @item ly:context-set-property!
1301 establecer el valor de una propiedad de contexto
1303 @item ly:context-grob-definition
1305 recuperar el valor de una propiedad de un grob
1307 @item ly:context-pushpop-property
1308 hacer una sobreescritura temporal
1309 (@code{\temporary@tie{}\override}) o una reversión
1310 (@code{\revert}) sobre una propiedad de un grob
1313 El ejemplo siguiente recupera el valor actual de @code{fontSize},
1314 y a continuación lo dobla:
1316 @lilypond[quote,verbatim]
1320 (let ((fontSize (ly:context-property context 'fontSize)))
1321 (ly:context-set-property! context 'fontSize (+ fontSize 6))))
1332 El ejemplo siguiente recupera los colores actuales de los grobs
1333 @code{NoteHead}, @code{Stem} y @code{Beam}, y a continuación los
1334 modifica para que tengan un matiz menos saturado.
1336 @lilypond[quote,verbatim]
1340 (define (desaturate-grob grob)
1341 (let* ((grob-def (ly:context-grob-definition context grob))
1342 (color (ly:assoc-get 'color grob-def black))
1343 (new-color (map (lambda (x) (min 1 (/ (1+ x) 2))) color)))
1344 (ly:context-pushpop-property context grob 'color new-color)))
1345 (for-each desaturate-grob '(NoteHead Stem Beam)))
1349 g'8[ g] \desaturate g[ g] \desaturate g[ g]
1350 \override NoteHead.color = #darkred
1351 \override Stem.color = #darkred
1352 \override Beam.color = #darkred
1353 g[ g] \desaturate g[ g] \desaturate g[ g]
1358 Esto puede implementarse también como una función musical, con el
1359 objeto de restringir las modificaciones a un único bloque de
1360 música. Observe cómo se usa @code{ly:context-pushpop-property}
1361 tanto como una sobreescritura temporal
1362 (@code{\temporary@tie{}\override}) como una reversión
1365 @lilypond[quote,verbatim]
1367 #(define-music-function
1372 (define (desaturate-grob grob)
1373 (let* ((grob-def (ly:context-grob-definition context grob))
1374 (color (ly:assoc-get 'color grob-def black))
1375 (new-color (map (lambda (x) (min 1 (/ (1+ x) 2))) color)))
1376 (ly:context-pushpop-property context grob 'color new-color)))
1377 (for-each desaturate-grob '(NoteHead Stem Beam)))
1381 (define (revert-color grob)
1382 (ly:context-pushpop-property context grob 'color))
1383 (for-each revert-color '(NoteHead Stem Beam)))
1387 \override NoteHead.color = #darkblue
1388 \override Stem.color = #darkblue
1389 \override Beam.color = #darkblue
1391 \desaturate { d c b a }
1397 @node Ejecutar una función sobre todos los objetos de la presentación
1398 @subsection Ejecutar una función sobre todos los objetos de la presentación
1399 @translationof Running a function on all layout objects
1401 @cindex código, llamar sobre objetos de presentación
1402 @funindex \applyOutput
1404 La manera más versátil de realizar el ajuste fino de un objeto es
1405 @code{\applyOutput}, que funciona insertando un evento dentro del
1406 contexto especificado (@rinternals{ApplyOutputEvent}). Su
1410 \applyOutput @var{Contexto} @var{proc}
1416 \applyOutput @var{Context}.@var{Grob} @var{proc}
1420 donde @code{@var{proc}} es una función de Scheme que toma tres
1423 Al interpretarse, la función @code{@var{proc}} se llama para cada
1424 objeto de presentación (con el nombre del grob @var{Grob} si se
1425 especifica) que se encuentra en el contexto @code{@var{Contexto}}
1426 en el tiempo actual, con los siguientes argumentos:
1429 @item el propio objeto de presentación,
1430 @item el contexto en que se creó el objeto de presentación, y
1431 @item el contexto en que se procesa @code{\applyOutput}.
1435 Además, la causa del objeto de presentación, es decir el objeto o
1436 expresión musical que es responsable de haberlo creado, está en la
1437 propiedad @code{cause} del objeto. Por ejemplo, para la cabeza de
1438 una nota, éste es un evento @rinternals{NoteHead}, y para un
1439 objeto plica, éste es un objeto @rinternals{Stem}.
1441 He aquí una función que usar para @code{\applyOutput}; borra las
1442 cabezas de las notas que están sobre la línea central y junto a
1445 @lilypond[quote,verbatim,ragged-right]
1446 #(define (blanker grob grob-origin context)
1447 (if (< (abs (ly:grob-property grob 'staff-position)) 2)
1448 (set! (ly:grob-property grob 'transparent) #t)))
1451 a'4 e8 <<\applyOutput Voice.NoteHead #blanker a c d>> b2
1455 Para que @var{función} se interprete en los niveles de
1456 @code{Score} o de @code{Staff} utilice estas formas:
1459 \applyOutput Score@dots{}
1460 \applyOutput Staff@dots{}
1464 @node Funciones de callback
1465 @section Funciones de callback
1466 @translationof Callback functions
1468 Las propiedades (como @code{thickness} (grosor), @code{direction}
1469 (dirección), etc.) se pueden establecer a valores fijos con
1473 \override Stem.thickness = #2.0
1476 Las propiedades pueden fijarse también a un procedimiento de
1479 @lilypond[fragment,verbatim,quote]
1480 \override Stem.thickness = #(lambda (grob)
1481 (if (= UP (ly:grob-property grob 'direction))
1484 \relative { c'' b a g b a g b }
1488 En este caso, el procedimiento se ejecuta tan pronto como el valor
1489 de la propiedad se reclama durante el proceso de formateo.
1491 Casi todo el motor de tipografiado está manejado por estos
1492 @emph{callbacks}. Entre las propiedades que usan normalmente
1493 @emph{callbacks} están
1497 La rutina de impresión, que construye un dibujo para el símbolo
1499 La rutina que establece la posición horizontal
1501 La rutina que calcula la anchura de un objeto
1504 El procedimiento siempre toma un argumento único, que es el grob
1505 (el objeto gráfico).
1507 Dicho procedimiento puede acceder al valor usual de la propiedad,
1508 llamando en primer lugar a la función que es el @q{callback} usual
1509 para esa propiedad, y que puede verse en el manual de referencia
1510 interna o en el archivo 'define-grobs.scm':
1514 \override Flag.X-offset = #(lambda (flag)
1515 (let ((default (ly:flag::calc-x-offset flag)))
1521 Desde dentro de un callback, el método más fácil para evaluar un
1522 elemento de marcado es usar grob-interpret-markup. Por ejemplo:
1525 mi-callback = #(lambda (grob)
1526 (grob-interpret-markup grob (markup "fulanito")))
1531 @n ode Código de Scheme en línea
1532 @s ection Código de Scheme en línea
1533 @t ranslationof Inline Scheme code
1535 TODO: after this section had been written, LilyPond has improved
1536 to the point that finding a @emph{simple} example where one would
1537 @emph{have} to revert to Scheme has become rather hard.
1539 Until this section gets a rewrite, let's pretend we don't know.
1541 La principal desventaja de @code{\tweak} es su inflexibilidad
1542 sintáctica. Por ejemplo, lo siguiente produce un error de sintaxis (o
1543 más bien: así lo hacía en algún momento del pasado):
1546 F = \tweak font-size #-3 -\flageolet
1554 Usando Scheme, se puede dar un rodeo a este problema. La ruta hacia
1555 el resultado se da en @ref{Añadir articulaciones a las notas
1556 (ejemplo)}, especialmente cómo usar @code{\displayMusic} como guía de
1560 F = #(let ((m (make-music 'ArticulationEvent
1561 'articulation-type "flageolet")))
1562 (set! (ly:music-property m 'tweaks)
1563 (acons 'font-size -3
1564 (ly:music-property m 'tweaks)))
1573 Aquí, las propiedades @code{tweaks} del objeto flageolet @code{m}
1574 (creado con @code{make-music}) se extraen con
1575 @code{ly:music-property}, se antepone un nuevo par clave-valor para
1576 cambiar el tamaño de la tipografía a la lista de propiedades con la
1577 función de Scheme @code{acons}, y finalmente el resultado se escribe
1578 de nuevo con @code{set!}. El último elemento del bloque @code{let} es
1579 el valor de retorno, el propio @code{m}.
1584 @node Trucos difíciles
1585 @section Trucos difíciles
1586 @translationof Difficult tweaks
1588 Hay un cierto número de tipos de ajustes difíciles.
1594 Un tipo de ajuste difícil es la apariencia de los objetos de
1595 extensión, como las ligaduras de expresión y de unión.
1596 Inicialmente, sólo se crea uno de estos objetos, y pueden
1597 ajustarse con el mecanismo normal. Sin embargo, en ciertos casos
1598 los objetos extensores cruzan los saltos de línea. Si esto
1599 ocurre, estos objetos se clonan. Se crea un objeto distinto por
1600 cada sistema en que se encuentra. Éstos son clones del objeto
1601 original y heredan todas sus propiedades, incluidos los
1604 En otras palabras, un @code{\override} siempre afecta a todas las
1605 piezas de un objeto de extensión fragmentado. Para cambiar sólo
1606 una parte de un extensor en el salto de línea, es necesario
1607 inmiscuirse en el proceso de formateado. El @emph{callback}
1608 @code{after-line-breaking} contiene el procedimiento Scheme que se
1609 llama después de que se han determinado los saltos de línea, y los
1610 objetos de presentación han sido divididos sobre los distintos
1613 En el ejemplo siguiente, definimos un procedimiento
1614 @code{my-callback}. Este procedimiento
1618 determina si hemos sido divididos por los saltos de línea
1620 en caso afirmativo, reúne todos los objetos divididos
1622 comprueba si somos el último de los objetos divididos
1624 en caso afirmativo, establece @code{extra-offset}.
1627 Este procedimiento se instala en @rinternals{Tie} (ligadura de
1628 unión), de forma que la última parte de la ligadura dividida se
1629 traslada hacia arriba.
1631 @lilypond[quote,verbatim,ragged-right]
1632 #(define (my-callback grob)
1634 ;; have we been split?
1635 (orig (ly:grob-original grob))
1637 ;; if yes, get the split pieces (our siblings)
1638 (siblings (if (ly:grob? orig)
1639 (ly:spanner-broken-into orig)
1642 (if (and (>= (length siblings) 2)
1643 (eq? (car (last-pair siblings)) grob))
1644 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1647 \override Tie.after-line-breaking =
1655 Al aplicar este truco, la nueva función de callback
1656 @code{after-line-breaking} también debe llamar a la antigua, si
1657 existe este valor predeterminado. Por ejemplo, si se usa con
1658 @code{Hairpin}, se debe llamar también a
1659 @code{ly:spanner::kill-zero-spanned-time}.
1662 @item Algunos objetos no se pueden cambiar con @code{\override} por
1663 razones técnicas. Son ejemplos @code{NonMusicalPaperColumn} y
1664 @code{PaperColumn}. Se pueden cambiar con la función
1665 @code{\overrideProperty} que funciona de forma similar a
1666 @code{\once \override}, pero usa una sintaxis distinta.
1670 Score.NonMusicalPaperColumn % Nombre del grob
1671 . line-break-system-details % Nombre de la propiedad
1672 . next-padding % Nombre de la subpropiedad, opcional
1676 Observe, sin embargo, que @code{\override}, aplicado a
1677 @code{NonMusicalPaperColumn} y a @code{PaperColumn}, aún funciona
1678 como se espera dentro de los bloques @code{\context}.
1683 @node Interfaces de Scheme de LilyPond
1684 @chapter Interfaces de Scheme de LilyPond
1685 @translationof LilyPond Scheme interfaces
1687 Este capítulo cubre las diversas herramientas proporcionadas por
1688 LilyPond como ayuda a los programadores de Scheme a extraer e
1689 introducir información de los flujos musicales.
1691 HACER @c TODO -- figure out what goes in here and how to organize it