1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: es -*-
2 @c This file is part of extending.tely
4 Translation of GIT committish: 41c8bf63a7cc180746eace9b9e5278f541be0229
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. Si no
17 está familiarizado con Scheme, le conviene leer nuestro tutorial de
18 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::
29 * Código de Scheme en línea::
33 @node Bloques de código de LilyPond
34 @section Bloques de código de LilyPond
35 @translationof LilyPond code blocks
37 @cindex Bloques de código de LilyPond
38 @cindex LilyPond, bloques de código de
39 @funindex #@{ @dots{} #@}
43 La creación de expresiones musicales en Scheme puede ser una tarea
44 tediosa porque a veces presentan muchos niveles de profundidad de
45 anidamiento y el código resultante es grande. Para algunas tareas
46 sencillas, esto puede evitarse utilizando bloques de código de
47 LilyPond, que permiten usar la sintaxis ordinaria de LilyPond
50 Los bloques de código de LilyPond tienen el siguiente aspecto:
52 #@{ @var{código de LilyPond} #@}
55 He aquí un ejemplo trivial:
57 @lilypond[verbatim,quote]
58 ritpp = #(define-event-function () ()
65 Los bloques de código de LilyPond se pueden usar en cualquier
66 lugar en el que se pueda escribir código de Scheme. El lector de
67 Scheme en efecto se modifica para que pueda incorporar bloques de
68 código de LilyPond y pueda ocuparse de las expresiones de Scheme
69 incrustadas que comienzan por @code{$} y@w{ }@code{#}.
71 @cindex parser (function argument)
74 El lector extrae el bloque de código de LilyPond y genera una
75 llamada en tiempo de ejecución al analizador sintáctico para que
76 interprete el código de LilyPond. Las expresiones de Scheme
77 incrustadas en el código de LilyPond se evalúan dentro del entorno
78 lóexico del bloque de código de LilyPond, de manera que puede
79 accederse a todas las variables locales y los parámetros de
80 función que están disponibles en el punto en que se escribe el
81 bloque de código de LilyPond. Las variables definidas en otros
82 módulos de Scheme, como los módulos que contienen bloques
83 @code{\header} y @code{\layout}, no están accesibles como
84 variables de Scheme, es decir, precedidas de@tie{}@code{#}, pero
85 se puede acceder a ellas como variables de LilyPond, es decir,
86 precedidas de@tie{}@code{\}.
88 Si @code{location} (véase @ref{Funciones de Scheme}) se refiere a una
89 posición de entrada válida (como lo hace normalmente dentro de las
90 funciones musicales o de Scheme), toda la música generada dentro
91 del bloque de código tiene su @samp{origin} establecido a
94 Un bloque de código de LilyPond puede contener cualquier cosa que
95 podríamos utilizar en la parte derecha de una asignación. Además, un
96 bloque de LilyPond vacío corresponde a una expresión musical vacía, y
97 un bloque de LilyPond que contiene varios eventos musicales se
98 convierte en una expresión de música secuencial.
100 @node Funciones de Scheme
101 @section Funciones de Scheme
102 @translationof Scheme functions
103 @cindex Scheme, funciones de (sintaxis de LilyPond)
105 Las @emph{funciones de Scheme} son procedimientos de Scheme que pueden
106 crear expresiones de Scheme a partir de código de entrada escrito en
107 la sintaxis de LilyPond. Se pueden llamar desde prácticamente
108 cualquier lugar en el que se permita el uso de @code{#} para la
109 especificación de un valor en sintaxis de Scheme. Mientras que Scheme
110 tiene funciones propias, este capítulo se ocupa de las funciones
111 @emph{sintácticas}, funciones que reciben argumentos especificados en
112 la sintaxis de LilyPond.
115 * Definición de funciones de Scheme::
116 * Uso de las funciones de Scheme::
117 * Funciones de Scheme vacías::
120 @node Definición de funciones de Scheme
121 @subsection Definición de funciones de Scheme
122 @translationof Scheme function definitions
123 @funindex define-scheme-function
125 La forma general de la definición de una función de Scheme es:
129 #(define-scheme-function
130 (@var{arg1} @var{arg2} @dots{})
131 (@var{tipo1?} @var{tipo2?} @dots{})
138 @multitable @columnfractions .33 .66
140 @tab tiene que ser literalmente @code{parser} para dar a los bloques de código
141 de LilyPond (@code{#@{}@dots{}@code{#@}}) acceso al analizador
144 @item @code{location}
145 @tab tiene que ser literalmente @code{location} para ofrecer acceso al
146 objeto de situación de la entrada, que se usa para ofrecer
147 menssajes de error con nombres de archivo y números de línea.
149 @item @code{@var{argN}}
150 @tab @var{n}-ésimo argumento
152 @item @code{@var{typeN?}}
153 @tab un @emph{predicado de tipo} de Scheme para el que @code{@var{argN}}
154 debe devolver @code{#t}.
156 También existe una forma especial @code{(@emph{predicate?}
157 @emph{default})} para especificar argumentos opcionales. Si el
158 argumento actual no está presente cuando se ll ama a la función, el
159 valor predeterminado se emplea en sustitución. Los valores
160 predeterminados se evalúan en tiempo de definición (¡incluyendo los
161 bloques de código de LilyPond!), de manera que se necesitamos un valor
162 por omisión calculado en tiempo de ejecución, debemos escribir en su
163 lugar un valor especial que podamos reconocer fácilmente. Si
164 escribimos el predicado entre paréntesis pero no lo seguimos por el
165 valor predeterminado, se usa @code{#f} como valor por omisión. Los
166 valores por omisión no se verifican con @emph{predicate?} en tiempo de
167 definición ni en tiempo de ejecución: es nuestra responsabilidad
168 tratar con los valores que especifiquemos. Los valores por omisión
169 que son expresiones musicales se copian mientras se establece
170 @code{origin} al parámetro @code{location}.
172 @item @code{@var{cuerpo}}
173 @tab una secuencia de formas de Scheme que se evalúan ordenadamente; la
174 última forma de la secuencia se usa como el valor de retorno de la
175 función de Scheme. Puede contener bloques de código de LilyPond
176 encerrados entre llaves con almohadillas
177 (@tie{}@w{@code{#@{@dots{}#@}}}@tie{}), como se describe en
178 @ref{Bloques de código de LilyPond}. Dentro de los bloques de código
179 de LilyPond, use el símbolo @code{#} para hacer referencia a
180 argumentos de función (p.ej. @samp{#arg1}) o para iniciar una
181 expresión en línea de Scheme que contenga argumentos de función
182 (p.ej. @w{@samp{#(cons arg1 arg2)}}). Donde las expresiones de Scheme
183 normales que usan @code{#} no funcionan, podríamos necesitar volver a
184 expresiones de Scheme inmediatas que usan @code{$}, como por ejemplo
187 Si nuestra función devuelve una expresión musical, recibe un valor
192 La idoneidad de los argumentos para los predicados viene determinada
193 mediante llamadas reales al predicado después de que LilyPond ya las
194 ha convertido en una expresión de Scheme. Como consecuencia, el
195 argumento se puede especificar en la sintaxis de Scheme si se desea
196 (precedido de @code{#} o como resultado de haber llamado a una función
197 de Scheme), pero LilyPond también convierte algunas construcciones de
198 LilyPond en Scheme antes de hacer efectivamente la comprobación del
199 predicado sobre ellas. Actualmente se encuentran entre ellas la
200 música, los post-eventos, las cadenas simples (entrecomilladas o no),
201 los números, los elementos de marcado y de listas de marcado, score
202 (partitura), book (libro), bookpart (parte de libro), las definiciones
203 de contexto y los bloques de definición de salida.
205 Para ciertos tipos de expresión (como la mayor parte de la música que
206 no está encerrada entre llaves) LilyPond necesita más allá de la
207 expresión misma para poder determinar su final. Si tal expresión se
208 considerase un argumento opcional mediante la evaluación de su
209 predicado, LilyPond no podría recuperarse después de decidir que la
210 expresión no se corresponde con el parámetro. Así, ciertas formas de
211 música necesitan ir encerradas entre llaves para poder considerarlas
212 como aceptables bajo algunas circunstancias. LilyPond resuelve
213 algunas otras ambigüedades mediante la comprobación con funciones de
214 predicado: ¿es @samp{-3} un post-evento de digitación o un número
215 negativo? ¿Es @code{"a" 4} en el modo de letra una cadena seguida por
216 un número, o un evento de letra con la duración @code{4}? LilyPond
217 prueba el predicado del argumento sobre diversas interpretaciones
218 sucesivas hasta que lo consigue, con un orden diseñado para minimizar
219 las interpretaciones poco consistentes y la lectura por adelantado.
221 Por ejemplo, un predicado que acepta tanto expresiones musicales como
222 alturas consideraría que @code{c''} es una altura en lugar de una
223 expresión musical. Las duraciones o post-eventos que siguieran
224 inmediatamente podrían no funcionar con dicha interpretación. Así
225 pues, es mejor evitar los predicados excesivamente permisivos como
226 @code{scheme?} cuando la aplicación requeriría tipos de argumento más
229 Para ver una lista de los predicados de tipo disponibles, consulte
230 @ruser{Predicados de tipo predefinidos}.
234 Referencia de la notación:
235 @ruser{Predicados de tipo predefinidos}.
238 @file{lily/music-scheme.cc},
243 @node Uso de las funciones de Scheme
244 @subsection Uso de las funciones de Scheme
245 @translationof Scheme function usage
247 Las funciones de Scheme se pueden llamar casi desde cualquier lugar en
248 que puede escribirse una expresión de Scheme que comience con la
249 almohadilla@tie{}@code{#}. Llamamos a una función de Scheme
250 escribiendo su nombre precedido de la barra invertida@tie{}@code{\}, y
251 seguido por sus argumentos. Una vez que un argumento opcional no
252 corresponde a ningún argumento, LilyPond se salta este argumento y
253 todos los que le siguen, sustituyéndolos por su valor por omisión
254 especificado, y @q{recupera} el argumento que no correspondía al lugar
255 del siguiente argumento obligatorio. Dado que el argumento recuperado
256 necesita ir a algún lugar, los argumentos opcionales no se consideran
257 realmente opcionales a no ser que vayan seguidos de un argumento
260 Existe una excepción: si escribimos @code{\default} en el lugar de un
261 argumento opcional, este argumento y todos los argumentos opcionales
262 que le siguen se saltan y se sustituyen por sus valores
263 predeterminados. Esto funciona incluso si no sigue ningún argumento
264 obligatorio porque @code{\default} no necesita recuperarse. Las
265 instrucciones @code{mark} y @code{key} hacen uso de este truco para
266 ofrecer su comportamiento predeterminado cuando van seguidas solamente
269 Aparte de los lugares en que se requiere un valor de Scheme hay
270 ciertos sitios en que se aceptan expresiones de almohadilla @code{#} y
271 se evalúan por sus efectos secundarios, pero por lo demás se ignoran.
272 Son, mayormente, los lugares en que también sería aceptable colocar
275 Dado que no es buena idea devolver valores que puedan malinterpretarse
276 en algún contexto, debería usar funciones de Scheme normales solo para
277 los casos en que siempre se devuelve un valor útil, y usar funciones
278 de Scheme vacías (@pxref{Funciones de Scheme vacías}) en caso
282 @node Funciones de Scheme vacías
283 @subsection Funciones de Scheme vacías
284 @translationof Void scheme functions
285 @funindex define-void-function
288 En ocasiones, un procedimiento se ejecuta con el objeto de llevar a
289 cabo alguna acción más que para devolver un valor. Algunos lenguajes
290 de programación (como C y Scheme) usan las funciones para los dos
291 conceptos y se limitan a descartar el valor devuelto (usualmente
292 haciendo que cualquier expresión pueda actuar como instrucción,
293 ignorando el resultado devuelto). Esto puede parecer inteligente pero
294 es propenso a errores: casi todos los compiladores de C de hoy en día
295 emiten advertencias cuando se descarta una expresión no vacía. Para
296 muchas funciones que ejecutan una acción, los estándares de Scheme
297 declaran que el valor de retorno sea no especificado. Guile, el
298 intérprete de Scheme de LilyPond, tiene un valor único
299 @code{*unspecified*} que en tales casos devuelve de forma usual (como
300 cuando se usa directamente @code{set!} sobre una variable), pero
301 desgraciadamente no de forma consistente.
303 Definir una función de LilyPond con @code{define-void-function}
304 asegura que se devuelve este valor especial, el único valor que
305 satisface el predicado @code{void?}.
309 #(define-void-function
312 (ly:set-option 'point-and-click #f))
314 \noApuntarYPulsar % desactivar la función de apuntar y pulsar
317 Si queremos evaluar una expresión sólo por su efecto colateral y no
318 queremos que se interprete ningún valor que pueda devolver, podemos
319 hacerlo anteponiendo el prefijo @code{\void}:
322 \void #(hashq-set! some-table some-key some-value)
325 De esta forma podemos asegurar que LilyPond no asignará ningún
326 significado al valor devuelto, independientemente de dónde lo
327 encuentre. También funciona para funciones musicales como
328 @code{\displayMusic}.
330 @node Funciones musicales
331 @section Funciones musicales
332 @translationof Music functions
334 @cindex funciones musicales
336 Las @emph{funciones musicales} son procedimientos de Scheme que pueden
337 crear automáticamente expresiones musicales, y se pueden usar para
338 simplificar enormemente el archivo de entrada.
341 * Definiciones de funciones musicales::
342 * Uso de las funciones musicales::
343 * Funciones de sustitución sencillas::
344 * Funciones de sustitución intermedias::
345 * Matemáticas dentro de las funciones::
346 * Funciones sin argumentos::
347 * Funciones musicales vacías::
351 @node Definiciones de funciones musicales
352 @subsection Definiciones de funciones musicales
353 @translationof Music function definitions
354 @cindex definición de funciones musicales
355 @funindex define-music-function
357 La forma general para definir funciones musicales es:
361 #(define-music-function
362 (@var{arg1} @var{arg2} @dots{})
363 (@var{tipo1?} @var{tipo2?} @dots{})
368 de forma bastante análoga a @ref{Definición de funciones de Scheme}.
369 Lo más probable es que el @var{cuerpo} sea un
370 @ref{Bloques de código de LilyPond,bloque de código de LilyPond}.
372 Para ver una lista de los predicados de tipo disponibles, consulte
373 @ruser{Predicados de tipo predefinidos}.
377 Referencia de la notación:
378 @ruser{Predicados de tipo predefinidos}.
381 @file{lily/music-scheme.cc},
386 @node Uso de las funciones musicales
387 @subsection Uso de las funciones musicales
388 @translationof Music function usage
390 Las funciones musicales se pueden actualmente utilizar en varios
391 lugares. Dependiendo de dónde se usan, son de aplicación ciertas
392 restricciones para que sea posible su análisis sintáctico de forma
393 no ambigua. El resultado que devuelve una función musical debe ser
394 compatible con el contexto desde el que se la llama.
398 En el nivel superior dentro de una expresión musical. Aquí
399 no se aplica ninguna restricción.
402 Como un post-evento, que comienza explícitamente con un indicador de
403 dirección (a elegir entre @code{-}, @code{^} @w{y @code{_}}).
405 En este caso, no podemos usar una expresión musical @emph{abierta}
406 como último argumento, que terminaría en una expresión musical
407 capaz de aceptar post-eventos adicionales.
410 Como componente de un acorde. La expresión devuelta debe ser
411 del tipo @code{rhythmic-event}, probablemente un @code{NoteEvent}.
415 Las reglas especiales para los argumentos del final hacen posible
416 escribir funciones polimórficas como @code{\tweak} que se pueden
417 aplicar a construcciones distintas.
419 @node Funciones de sustitución sencillas
420 @subsection Funciones de sustitución sencillas
421 @translationof Simple substitution functions
423 Una función de sustitución sencilla es una función musical cuya
424 expresión musical de salida está escrita en código de LilyPond
425 y contiene argumentos de la función en la expresión de salida.
426 Están descritas en @ruser{Ejemplos de funciones de sustitución}.
429 @node Funciones de sustitución intermedias
430 @subsection Funciones de sustitución intermedias
431 @translationof Intermediate substitution functions
433 Las funciones de sustitución intermedias contienen una
434 mezcla de código de Scheme y de LilyPond
435 dentro de la expresión musical que se devuelve.
437 Algunas instrucciones @code{\override} requieren un argumento que
438 consiste en una pareja de números (llamada una @emph{célula cons} en
441 La pareja se puede pasar directamente dentro de la función musical,
442 usando una variable @code{pair?}:
446 #(define-music-function
450 \once \override Beam.positions = #principio-final
454 \barraManual #'(3 . 6) c8 d e f
458 De forma alternativa, los números que componen la pareja se pueden
459 pasar como argumentos separados, y el código de Scheme que se ha usado
460 para crear la pareja se puede incluir dentro de la expresión musical:
462 @lilypond[quote,verbatim,ragged-right]
464 #(define-music-function
468 \once \override Beam.positions = #(cons beg end)
472 \manualBeam #3 #6 c8 d e f
477 @cindex sobreescrituras temporales
478 @cindex temporales, sobreescrituras
479 @cindex propiedades, recuperar valor anterior
481 Las propiedades se mantienen conceptualmente utilizando una pila
482 por cada propiedad, por cada grob y por cada contexto. Las
483 funciones musicales pueden requerir la sobreescritura de una o
484 varias propiedades durante el tiempo de duración de la función,
485 restaurándolas a sus valores previos antes de salir. Sin embargo,
486 las sobreescrituras normales extraen y descartan la cima de la
487 pila de propiedades actual antes de introducir un valor en ella,
488 de manera que el valor anterior de la propiedad se pierde cuando
489 se sobreescribe. Si se quiere preservar el valor anterior, hay
490 que preceder la instrucción @code{\override} con la palabra clave
491 @code{\temporary}, así:
494 \temporary \override @dots{}
497 El uso de @code{\temporary} hace que se borre la propiedad
498 (normalmente fijada a un cierto valor) @code{pop-first} de la
499 sobreescritura, de forma que el valor anterior no se extrae de la
500 pila de propiedades antes de poner en ella el valor nuevo. Cuando
501 una instrucción @code{\revert} posterior extrae el avlor
502 sobreescrito temporalmente, volverá a emerger el valor anterior.
504 En otras palabras, una llamada a @code{\temporary \override} y a
505 continuación otra a @code{\revert} sobre la misma propiedad, tiene
506 un valor neto que es nulo. De forma similar, la combinación en
507 secuencia de @code{\temporary} y @code{\undo} sobre la misma
508 música que contiene las sobreescrituras, tiene un efecto neto
511 He aquí un ejemplo de una función musical que utiliza lo expuesto
512 anteriormente. El uso de @code{\temporary} asegura que los
513 valores de las propiedades @code{cross-staff} y @code{style} se
514 restauran a la salida a los valores que tenían cuando se llamó a
515 la función @code{crossStaff}. Sin @code{\temporary}, a la salida
516 se habrían fijado los valores predeterminados.
520 #(define-music-function (notes) (ly:music?)
521 (_i "Create cross-staff stems")
523 \temporary \override Stem.cross-staff = #cross-staff-connect
524 \temporary \override Flag.style = #'no-flag
526 \revert Stem.cross-staff
532 @node Matemáticas dentro de las funciones
533 @subsection Matemáticas dentro de las funciones
534 @translationof Mathematics in functions
536 Las funciones musicales pueden contar con programación de Scheme
537 además de la simple sustitución:
539 @lilypond[quote,verbatim,ragged-right]
541 #(define-music-function
545 \override Stem.length = #(* 7.0 mag)
546 \override NoteHead.font-size =
547 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
552 \revert NoteHead.font-size
557 \AltOn #1.5 c c \AltOff c2
562 Este ejemplo se puede reescribir de forma que pase expresiones
565 @lilypond[quote,verbatim,ragged-right]
567 #(define-music-function
571 \override Stem.length = #(* 7.0 mag)
572 \override NoteHead.font-size =
573 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
576 \revert NoteHead.font-size
580 c'2 \withAlt #0.5 { c4 c }
581 \withAlt #1.5 { c c } c2
586 @node Funciones sin argumentos
587 @subsection Funciones sin argumentos
588 @translationof Functions without arguments
590 En casi todos los casos, una función sin argumentos se debe escribir
594 dolce = \markup@{ \italic \bold dolce @}
597 Sin embargo, en raras ocasiones puede ser de utilidad crear una
598 función musical sin argumentos:
601 mostrarNumeroDeCompas =
602 #(define-music-function
605 (if (eq? #t (ly:get-option 'display-bar-numbers))
606 #@{ \once \override Score.BarNumber.break-visibility = ##f #@}
610 Para la impresión real de los números de compás donde se llama a esta
611 función, invoque a @command{lilypond} con
614 lilypond -d display-bar-numbers ARCHIVO.ly
618 @node Funciones musicales vacías
619 @subsection Funciones musicales vacías
620 @translationof Void music functions
622 Una función musical debe devolver una expresión musical. Si quiere
623 ejecutar una función exclusivamente por sus efectos secundarios,
624 debería usar @code{define-void-function}. Pero
625 puede haber casos en los que a veces queremos producir una expresión
626 musical, y a veces no (como en el ejemplo anterior). Devolver una
627 expresión musical @code{void} (vacía) por medio de @code{#@{ #@}} lo
631 @node Funciones de eventos
632 @section Funciones de eventos
633 @translationof Event functions
634 @funindex define-event-function
635 @cindex event functions
637 Para usar una función musical en el lugar de un evento, tenemos que
638 escribir un indicador de dirección antes de ella. Pero a veces, ello
639 hace que se pierda la correspondencia con la sintaxis de las
640 construcciones que queremos sustituir. Por ejemplo, si queremos
641 escribir instrucciones de matiz dinámico, éstos se adjuntan
642 habitualmente sin indicador de dirección, como @code{c'\pp}. He aquí
643 una forma de escribir indicaciones dinámicas arbitrarias:
645 @lilypond[quote,verbatim,ragged-right]
646 dyn=#(define-event-function (arg) (markup?)
647 (make-dynamic-script arg))
648 \relative { c'\dyn pfsss }
651 Podríamos hacer lo mismo usando una función musical, pero entonces
652 tendríamos que escribir siempre un indicador de dirección antes de
653 llamarla, como @code{@w{c-\dyn pfsss}}.
656 @node Funciones de marcado
657 @section Funciones de marcado
658 @translationof Markup functions
660 Los elementos de marcado están implementados como funciones de Scheme
661 especiales que producen un objeto @code{Stencil} dada una serie de
666 * Construcción de elementos de marcado en Scheme::
667 * Cómo funcionan internamente los elementos de marcado::
668 * Definición de una instrucción de marcado nueva::
669 * Definición de nuevas instrucciones de lista de marcado::
672 @node Construcción de elementos de marcado en Scheme
673 @subsection Construcción de elementos de marcado en Scheme
674 @translationof Markup construction in Scheme
676 @cindex marcado, definir instrucciones de
677 @funindex \displayScheme
679 Las expresiones de marcado se representan internamente en Scheme
680 usando el macro @code{markup}:
686 Para ver una expresión de marcado en su forma de Scheme, utilice
687 la instrucción @code{\displayScheme}:
693 \line @{ \bold \italic "hola" \raise #0.4 "mundo" @}
694 \larger \line @{ fulano fulanito menganito @}
700 La compilación del código anterior envía a la consola lo
708 (#:bold (#:italic "hola") #:raise 0.4 "mundo")
711 (#:simple "fulano" #:simple "fulanito" #:simple "menganito")))))
714 Para evitar que el marcado se imprima en la página, use
715 @w{@samp{\void \displayScheme @var{marcado}}}. Asimismo, como
716 ocurre con la instrucción @code{\displayMusic}, la salida de
717 @code{\displayScheme} se puede guardar en un archivo externo.
718 Véase @ref{Presentación de las expresiones musicales}.
721 Este ejemplo muestra las principales reglas de traducción entre la
722 sintaxis del marcado normal de LilyPond y la sintaxis del marcado de
723 Scheme. La utilización de @code{#@{ @dots{} #@}} para escribir en la
724 sintaxis de LilyPond será con frecuencia lo más conveniente, pero
725 explicamos cómo usar la macro @code{markup} para obtener una solución
729 @multitable @columnfractions .3 .3
730 @item @b{LilyPond} @tab @b{Scheme}
731 @item @code{\markup marcado1} @tab @code{(markup marcado1)}
732 @item @code{\markup @{ marcado1 marcado2 @dots{} @}} @tab
733 @code{(markup marcado1 marcado2 @dots{} )}
734 @item @code{\instruccion} @tab @code{#:instruccion}
735 @item @code{\variable} @tab @code{variable}
736 @item @code{\center-column @{ @dots{} @}} @tab
737 @code{#:center-column ( @dots{} )}
738 @item @code{cadena} @tab @code{"cadena"}
739 @item @code{#argumento-de-scheme} @tab @code{argumento-de-scheme}
743 Todo el lenguaje Scheme está accesible dentro del macro @code{markup}.
744 Por ejemplo, podemos usar llamadas a funciones dentro de @code{markup}
745 para así manipular cadenas de caracteres. Esto es útil si se están
746 definiendo instrucciones de marcado nuevas (véase
747 @ref{Definición de una instrucción de marcado nueva}).
752 El argumento markup-list de instrucciones como @code{#:line},
753 @code{#:center} y @code{#:column} no puede ser una variable ni el
754 resultado de la llamada a una función.
757 (markup #:line (funcion-que-devuelve-marcados))
761 no es válido. Hay que usar las funciones @code{make-line-markup},
762 @code{make-center-markup} o @code{make-column-markup} en su lugar:
765 (markup (make-line-markup (funcion-que-devuelve-marcados)))
769 @node Cómo funcionan internamente los elementos de marcado
770 @subsection Cómo funcionan internamente los elementos de marcado
771 @translationof How markups work internally
773 En un elemento de marcado como
776 \raise #0.5 "ejemplo de texto"
780 @code{\raise} se representa en realidad por medio de la función
781 @code{raise-markup}. La expresión de marcado se almacena como
784 (list raise-markup 0.5 (list simple-markup "ejemplo de texto"))
787 Cuando el marcado se convierte en objetos imprimibles (Stencils o
788 sellos), se llama la función @code{raise-markup} como
792 @var{\objeto de marcado}
793 @var{lista de listas asociativas de propiedades}
795 @var{el marcado "ejemplo de texto"})
798 Primero la función @code{raise-markup} crea el sello para la cadena
799 @code{ejemplo de texto}, y después eleva el sello Stencil en 0.5
800 espacios de pentagrama. Este es un ejemplo bastante simple; en el
801 resto de la sección podrán verse ejemplos más complejos, así como en
802 @file{scm/define-markup-commands.scm}.
805 @node Definición de una instrucción de marcado nueva
806 @subsection Definición de una instrucción de marcado nueva
807 @translationof New markup command definition
809 Esta sección trata sobre la definición de nuevas instrucciones de
814 * Sintaxis de la definición de instrucciones de marcado::
815 * Acerca de las propiedades::
816 * Un ejemplo completo::
817 * Adaptación de instrucciones incorporadas::
820 @node Sintaxis de la definición de instrucciones de marcado
821 @unnumberedsubsubsec Sintaxis de la definición de instrucciones de marcado
822 @translationof Markup command definition syntax
824 Se pueden definir instrucciones de marcado nuevas usando el macro de
825 Scheme @code{define-markup-command}, en el nivel sintáctico superior.
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 @code{props},
852 se puede usar la palabra clave @code{#:properties} para especificar
853 qué propiedades se usan, así como sus valores predeterminados.
855 Los argumentos se distinguen según su tipo:
857 @item un marcado, que corresponde al predicado de tipo @code{markup?};
858 @item una lista de marcados, que corresponde al predicado de tipo
860 @item cualquier otro objeto de Scheme, que corresponde a predicados de tipo como
861 @code{list?}, @code{number?}, @code{boolean?}, etc.
864 No existe ninguna limitación en el orden de los argumentos (después de
865 los argumentos estándar @code{layout} y @code{props}). Sin embargo, las
866 funciones de marcado que toman un elemento de marcado como su último
867 argumento son un poco especiales porque podemos aplicarlas a una lista
868 de marcados y el resultado es una lista de marcados donde la función
869 de marcado (con los argumentos antecedentes especificados) se ha
870 aplicado a todos los elementos de la lista de marcados original.
872 Dado que la replicación de los argumentos precedentes para aplicar una
873 función de marcado a una lista de marcados es poco costosa
874 principalmente por los argumentos de Scheme, se evitan las caídas de
875 rendimiento simplemente mediante la utilización de argumentos de
876 Scheme para los argumentos antecedentes de las funciones de marcado
877 que toman un marcado como su último argumento.
881 @funindex interpret-markup
882 Las instrucciones de marcado tienen un ciclo de vida más bien
883 complejo. El cuerpo de la definición de una instrucción de marcado es
884 responsable de la conversión de los argumentos de la instrucción de
885 marcado en una expresión de sello que se devuelve. Muy a menudo esto
886 se lleva a cabo llamando a la función @code{interpret-markup} sobre
887 una expresión de marcado, pasándole los argumentos @var{layout} y
888 @var{props}. Por lo general, estos argumentos se conocen solamente en
889 una fase muy tardía de la composición tipográfica. Las expresiones de
890 marcado ya tienen sus componentes ensamblados dentro de expresiones de
891 marcado cuando se expanden las instrucciones @code{\markup} (dentro de
892 una expresión de LilyPond) o la macro @code{markup} (dentro de
893 Scheme). La evaluación y la comprobación de tipos de los argumentos
894 de la instrucción de marcado tiene lugar en el momento en que se
895 interpretan @code{\markup} o @code{markup}.
897 Pero la conversión real de expresiones de marcado en expresiones de
898 sello mediante la ejecución de los cuerpos de función de marcado solo
899 tienen lugar cuando se llama a @code{interpret-markup} sobre una
900 expresión de marcado.
902 @node Acerca de las propiedades
903 @unnumberedsubsubsec Acerca de las propiedades
904 @translationof On properties
906 Los argumentos @code{layout} y @code{props} de las instrucciones de
907 marcado traen a escena un contexto para la interpretación del marcado:
908 tamaño de la tipografía, grueso de línea, etc.
910 El argumento @code{layout} permite el acceso a las propiedades
911 definidas en los bloques @code{paper}, usando la función
912 @code{ly:output-def-lookup}. Por ejemplo, el grueso de línea (el
913 mismo que el que se usa en las partituras) se lee usando:
916 (ly:output-def-lookup layout 'line-width)
919 El argumento @code{props} hace accesibles algunas propiedades a las
920 instrucciones de marcado. Por ejemplo, cuando se interpreta el
921 marcado del título de un libro, todas las variables definidas dentro
922 del bloque @code{\header} se añaden automáticamente a @code{props}, de
923 manera que el marcado del título del libro puede acceder al título del
924 libro, el autor, etc. También es una forma de configurar el
925 comportamiento de una instrucción de marcado: por ejemplo, cuando una
926 instrucción utiliza tamaños de tipografía durante el procesado, el
927 tamaño se lee de @code{props} en vez de tener un argumento
928 @code{font-size}. El que llama a una instrucción de marcado puede
929 cambiar el valor de la propiedad del tamaño de la tipografía con el
930 objeto de modificar el comportamiento. Utilice la palabra clave
931 @code{#:properties} de @code{define-markup-command} para especificar
932 qué propiedades se deben leer a partir de los argumentos de
935 El ejemplo de la sección siguiente ilustra cómo acceder y
936 sobreescribir las propiedades de una instrucción de marcado.
939 @node Un ejemplo completo
940 @unnumberedsubsubsec Un ejemplo completo
941 @translationof A complete example
943 El ejemplo siguiente define una instrucción de marcado para trazar un
944 rectángulo doble alrededor de un fragmento de texto.
946 En primer lugar, necesitamos construir un resultado aproximado
947 utilizando marcados. Una consulta a @ruser{Instrucciones de marcado
948 de texto} nos muestra que es útil la instrucción @code{\box}:
950 @lilypond[quote,verbatim,ragged-right]
951 \markup \box \box HELLO
954 Ahora, consideramos que es preferible tener más separación entre el
955 texto y los rectángulos. Según la documentación de @code{\box}, esta
956 instrucción usa una propiedad @code{box-padding}, cuyo valor
957 predeterminado es 0.2. La documentación también menciona cómo
958 sobreescribir este valor:
960 @lilypond[quote,verbatim,ragged-right]
961 \markup \box \override #'(box-padding . 0.6) \box A
964 Después, el relleno o separación entre los dos rectángulos nos parece
965 muy pequeño, así que lo vamos a sobreescribir también:
967 @lilypond[quote,verbatim,ragged-right]
968 \markup \override #'(box-padding . 0.4) \box
969 \override #'(box-padding . 0.6) \box A
972 Repetir esta extensa instrucción de marcado una y otra vez sería un
973 quebradero de cabeza. Aquí es donde se necesita una instrucción de
974 marcado. Así pues, escribimos una instrucción de marcado
975 @code{double-box}, que toma un argumento (el texto). Dibuja los dos
976 rectángulos y añade una separación.
979 #(define-markup-command (double-box layout props text) (markup?)
980 "Trazar un rectángulo doble rodeando el texto."
981 (interpret-markup layout props
982 #@{\markup \override #'(box-padding . 0.4) \box
983 \override #'(box-padding . 0.6) \box @{ #text @}#@}))
986 o, de forma equivalente,
989 #(define-markup-command (double-box layout props text) (markup?)
990 "Trazar un rectángulo doble rodeando el texto."
991 (interpret-markup layout props
992 (markup #:override '(box-padding . 0.4) #:box
993 #:override '(box-padding . 0.6) #:box text)))
996 @code{text} es el nombre del argumento de la instrucción, y
997 @code{markup?} es el tipo: lo identifica como un elemento de marcado.
998 La función @code{interpret-markup} se usa en casi todas las
999 instrucciones de marcado: construye un sello, usando @code{layout},
1000 @code{props}, y un elemento de marcado. En el segundo caso, la marca
1001 se construye usando el macro de Scheme @code{markup}, véase
1002 @ref{Construcción de elementos de marcado en Scheme}. La
1003 transformación de una expresión @code{\markup} en una expresión de
1004 marcado de Scheme es directa.
1006 La instrucción nueva se puede usar como sigue:
1009 \markup \double-box A
1012 Sería buen hacer que la instrucción @code{double-box} fuera
1013 personalizable: aquí, los valores de relleno @code{box-padding} son
1014 fijos, y no se pueden cambiar por parte del usuario. Además, sería
1015 mejor distinguir la separación entre los dos rectángulos, del relleno
1016 entre el rectángulo interno y el texto. Así pues, introducimos una
1017 nueva propiedad, @code{inter-box-padding}, para el relleno entre los
1018 rectángulos. El @code{box-padding} se usará para el relleno interno.
1019 Ahora el código nuevo es como se ve a continuación:
1022 #(define-markup-command (double-box layout props text) (markup?)
1023 #:properties ((inter-box-padding 0.4)
1025 "Trazar un rectángulo doble rodeando el texto."
1026 (interpret-markup layout props
1027 #@{\markup \override #`(box-padding . ,inter-box-padding) \box
1028 \override #`(box-padding . ,box-padding) \box
1032 De nuevo, la versión equivalente que utiliza la macro de marcado sería:
1035 #(define-markup-command (double-box layout props text) (markup?)
1036 #:properties ((inter-box-padding 0.4)
1038 "Trazar un rectángulo doble rodeando el texto."
1039 (interpret-markup layout props
1040 (markup #:override `(box-padding . ,inter-box-padding) #:box
1041 #:override `(box-padding . ,box-padding) #:box text)))
1044 Aquí, la palabra clave @code{#:properties} se usa de manera que las
1045 propiedades @code{inter-box-padding} y @code{box-padding} se leen a
1046 partir del argumento @code{props}, y se les proporcionan unos valores
1047 predeterminados si las propiedades no están definidas.
1049 Después estos valores se usan para sobreescribir las propiedades
1050 @code{box-padding} usadas por las dos instrucciones @code{\box}.
1051 Observe el apóstrofo invertido y la coma en el argumento de
1052 @code{\override}: nos permiten introducir un valor de variable dentro
1053 de una expresión literal.
1055 Ahora, la instrucción se puede usar dentro de un elemento de marcado,
1056 y el relleno de los rectángulos se puede personalizar:
1058 @lilypond[quote,verbatim,ragged-right]
1059 #(define-markup-command (double-box layout props text) (markup?)
1060 #:properties ((inter-box-padding 0.4)
1062 "Draw a double box around text."
1063 (interpret-markup layout props
1064 #{\markup \override #`(box-padding . ,inter-box-padding) \box
1065 \override #`(box-padding . ,box-padding) \box
1068 \markup \double-box A
1069 \markup \override #'(inter-box-padding . 0.8) \double-box A
1070 \markup \override #'(box-padding . 1.0) \double-box A
1074 @node Adaptación de instrucciones incorporadas
1075 @unnumberedsubsubsec Adaptación de instrucciones incorporadas
1076 @translationof Adapting builtin commands
1078 Una buena manera de comenzar a escribir una instrucción de marcado
1079 nueva, es seguir el ejemplo de otra instrucción ya incorporada. Casi
1080 todas las instrucciones de marcado que están incorporadas en LilyPond
1081 se pueden encontrar en el archivo
1082 @file{scm/define-markup-commands.scm}.
1084 Por ejemplo, querríamos adaptar la instrucción @code{\draw-line}, para
1085 que trace una línea doble. La instrucción @code{\draw-line} está
1086 definida como sigue (se han suprimido los comentarios de
1090 (define-markup-command (draw-line layout props dest)
1093 #:properties ((thickness 1))
1094 "@dots{}documentación@dots{}"
1095 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
1099 (make-line-stencil th 0 0 x y)))
1102 Para definir una instrucción nueva basada en otra existente, copie la
1103 definición y cámbiele el nombre. La palabra clave @code{#:category}
1104 se puede eliminar sin miedo, pues sólo se utiliza para generar
1105 documentación de LilyPond, y no tiene ninguna utilidad para las
1106 instrucciones de marcado definidas por el usuario.
1109 (define-markup-command (draw-double-line layout props dest)
1111 #:properties ((thickness 1))
1112 "@dots{}documentación@dots{}"
1113 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
1117 (make-line-stencil th 0 0 x y)))
1120 A continuación se añade una propiedad para establecer la separación
1121 entre las dos líneas, llamada @code{line-gap}, con un valor
1122 predeterminado de p.ej. 0.6:
1125 (define-markup-command (draw-double-line layout props dest)
1127 #:properties ((thickness 1)
1129 "@dots{}documentación@dots{}"
1133 Finalmente, se añade el código para trazar las dos líneas. Se usan
1134 dos llamadas a @code{make-line-stencil} para trazar las líneas, y los
1135 sellos resultantes se combinan usando @code{ly:stencil-add}:
1137 @lilypond[quote,verbatim,ragged-right]
1138 #(define-markup-command (my-draw-line layout props dest)
1140 #:properties ((thickness 1)
1143 (let* ((th (* (ly:output-def-lookup layout 'line-thickness)
1147 (w (/ line-gap 2.0))
1148 (x (cond ((= dx 0) w)
1150 (else (/ w (sqrt (+ 1 (* (/ dx dy) (/ dx dy))))))))
1151 (y (* (if (< (* dx dy) 0) 1 -1)
1154 (else (/ w (sqrt (+ 1 (* (/ dy dx) (/ dy dx))))))))))
1155 (ly:stencil-add (make-line-stencil th x y (+ dx x) (+ dy y))
1156 (make-line-stencil th (- x) (- y) (- dx x) (- dy y)))))
1158 \markup \my-draw-line #'(4 . 3)
1159 \markup \override #'(line-gap . 1.2) \my-draw-line #'(4 . 3)
1163 @node Definición de nuevas instrucciones de lista de marcado
1164 @subsection Definición de nuevas instrucciones de lista de marcado
1165 @translationof New markup list command definition
1167 @funindex define-markup-list-command
1168 @funindex interpret-markup-list
1170 Las instrucciones de listas de marcado se definen con el macro de
1171 Scheme @code{define-markup-list-command}, que es similar al macro
1172 @code{define-markup-command} descrito en @ref{Definición de una
1173 instrucción de marcado nueva}, excepto que donde éste devuelve un
1174 sello único, aquél devuelve una lista de sellos.
1176 En el siguiente ejemplo se define una instrucción de lista de marcado
1177 @code{\paragraph}, que devuelve una lista de líneas justificadas,
1178 estando la primera de ellas sangrada. La anchura del sangrado se toma
1179 del argumento @code{props}.
1182 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1183 #:properties ((par-indent 2))
1184 (interpret-markup-list layout props
1185 #@{\markuplist \justified-lines @{ \hspace #par-indent #args @} #@}))
1189 La versión que usa solamente Scheme es más compleja:
1191 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1192 #:properties ((par-indent 2))
1193 (interpret-markup-list layout props
1194 (make-justified-lines-markup-list (cons (make-hspace-markup par-indent)
1198 Aparte de los argumentos usuales @code{layout} y @code{props}, la
1199 instrucción de lista de marcados @code{paragraph} toma un argumento de
1200 lista de marcados, llamado @code{args}. El predicado para listas de
1201 marcados es @code{markup-list?}.
1203 En primer lugar, la función toma el ancho del sangrado, una propiedad
1204 llamada aquí @code{par-indent}, de la lista de propiedades
1205 @code{props}. Si no se encuentra la propiedad, el valor
1206 predeterminado es @code{2}. Después, se hace una lista de líneas
1207 justificadas usando la instrucción incorporada de lista de marcados
1208 @code{\justified-lines}, que está relacionada con la función
1209 @code{make-justified-lines-markup-list}. Se añade un espacio
1210 horizontal al principio usando @code{\hspace} (o la función
1211 @code{make-hspace-markup}). Finalmente, la lista de marcados se
1212 interpreta usando la función @code{interpret-markup-list}.
1214 Esta nueva instrucción de lista de marcados se puede usar como sigue:
1219 El arte de la tipografía musical se llama \italic @{grabado (en plancha).@}
1220 El término deriva del proceso tradicional de impresión de música.
1221 hace sólo algunas décadas, las partituras se hacían cortando y estampando
1222 la música en una plancha de zinc o lata en una imagen invertida.
1224 \override-lines #'(par-indent . 4) \paragraph @{
1225 La plancha se tenía que entintar, y las depresiones causadas por los cortes
1226 y estampados retienen la tinta. Se formaba una imagen presionando el papel
1227 contra la plancha. El estampado y cortado se hacía completamente
1234 @node Contextos para programadores
1235 @section Contextos para programadores
1236 @translationof Contexts for programmers
1239 * Evaluación de contextos::
1240 * Ejecutar una función sobre todos los objetos de la presentación::
1243 @node Evaluación de contextos
1244 @subsection Evaluación de contextos
1245 @translationof Context evaluation
1247 @cindex código, llamadas durante la interpretación
1248 @funindex \applyContext
1250 Se pueden modificar los contextos durante la interpretación con código
1251 de Scheme. La sintaxis para esto es
1254 \applyContext @var{función}
1257 @code{@var{función}} debe ser una función de Scheme que toma un único
1258 argumento, que es el contexto al que aplicarla. El código siguiente
1259 imprime el número del compás actual sobre la salida estándar durante
1265 (format #t "\nSe nos ha llamado en el compás número ~a.\n"
1266 (ly:context-property x 'currentBarNumber)))
1270 @node Ejecutar una función sobre todos los objetos de la presentación
1271 @subsection Ejecutar una función sobre todos los objetos de la presentación
1272 @translationof Running a function on all layout objects
1274 @cindex código, llamar sobre objetos de presentación
1275 @funindex \applyOutput
1278 La manera más versátil de realizar el ajuste fino de un objeto es
1279 @code{\applyOutput}, que
1280 funciona insertando un evento dentro del contexto especificado
1281 (@rinternals{ApplyOutputEvent}). Su sintaxis es
1284 \applyOutput @var{Contexto} @var{proc}
1288 donde @code{@var{proc}} es una función de Scheme que toma tres argumentos.
1290 Al interpretarse, la función @code{@var{proc}} se llama para cada objeto de
1291 presentación que se encuentra en el contexto @code{@var{Contexto}}
1292 en el tiempo actual, con los siguientes argumentos:
1295 @item el propio objeto de presentación,
1296 @item el contexto en que se creó el objeto de presentación, y
1297 @item el contexto en que se procesa @code{\applyOutput}.
1301 Además, la causa del objeto de presentación, es decir el objeto o
1302 expresión musical que es responsable de haberlo creado, está en la
1303 propiedad @code{cause} del objeto. Por ejemplo, para la cabeza de una
1304 nota, éste es un evento @rinternals{NoteHead}, y para un objeto
1305 plica, éste es un objeto @rinternals{Stem}.
1307 He aquí una función que usar para @code{\applyOutput}; borra las
1308 cabezas de las notas que están sobre la línea central y junto a ella:
1310 @lilypond[quote,verbatim,ragged-right]
1311 #(define (blanker grob grob-origin context)
1312 (if (and (memq 'note-head-interface (ly:grob-interfaces grob))
1313 (< (abs (ly:grob-property grob 'staff-position)) 2))
1314 (set! (ly:grob-property grob 'transparent) #t)))
1317 a'4 e8 <<\applyOutput #'Voice #blanker a c d>> b2
1321 Para que @var{función} se interprete en los niveles de @code{Score} o de @code{Staff}
1322 utilice estas formas:
1325 \applyOutput #'Score #@var{función}
1326 \applyOutput #'Staff #@var{función}
1330 @node Funciones de callback
1331 @section Funciones de callback
1332 @translationof Callback functions
1334 Las propiedades (como @code{thickness} (grosor), @code{direction}
1335 (dirección), etc.) se pueden establecer a valores fijos con \override,
1339 \override Stem.thickness = #2.0
1342 Las propiedades pueden fijarse también a un procedimiento de Scheme,
1344 @lilypond[fragment,verbatim,quote]
1345 \override Stem.thickness = #(lambda (grob)
1346 (if (= UP (ly:grob-property grob 'direction))
1349 \relative { c'' b a g b a g b }
1353 En este caso, el procedimiento se ejecuta tan pronto como el valor de
1354 la propiedad se reclama durante el proceso de formateo.
1356 Casi todo el motor de tipografiado está manejado por estos
1357 @emph{callbacks}. Entre las propiedades que usan normalmente
1358 @emph{callbacks} están
1362 La rutina de impresión, que construye un dibujo para el símbolo
1364 La rutina que establece la posición horizontal
1366 La rutina que calcula la anchura de un objeto
1369 El procedimiento siempre toma un argumento único, que es el grob (el
1372 Dicho procedimiento puede acceder al valor usual de la propiedad,
1373 llamando en primer lugar a la función que es el @q{callback} usual
1374 para esa propiedad, y que puede verse en el manual de referencia
1375 interna o en el archivo 'define-grobs.scm':
1379 \override Flag.X-offset = #(lambda (flag)
1380 (let ((default (ly:flag::calc-x-offset flag)))
1386 Si se deben llamar rutinas con varios argumentos, el grob actual se
1387 puede insertar con una cerradura de grob. He aquí un ajuste
1388 procedente de @code{AccidentalSuggestion},
1392 ,(ly:make-simple-closure
1394 ,(ly:make-simple-closure
1395 (list ly:self-alignment-interface::centered-on-x-parent))
1396 ,(ly:make-simple-closure
1397 (list ly:self-alignment-interface::x-aligned-on-self)))))
1401 En este ejemplo, tanto
1402 @code{ly:self-alignment-interface::x-aligned-on-self} como
1403 @code{ly:self-alignment-interface::centered-on-x-parent} se llaman con
1404 el grob como argumento. El resultado se añade con la función
1405 @code{+}. Para asegurar que esta adición se ejecuta adecuadamente,
1406 todo ello se encierra dentro de @code{ly:make-simple-closure}.
1408 De hecho, usar un solo procedimiento como valor de una propiedad
1412 (ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
1416 El @code{ly:make-simple-closure} interior aporta el grob como
1417 argumento de @var{proc}, el exterior asegura que el resultado de la
1418 función es lo que se devuelve, en lugar del objeto
1419 @code{simple-closure}.
1421 Desde dentro de un callback, el método más fácil para evaluar un
1422 elemento de marcado es usar grob-interpret-markup. Por ejemplo:
1425 mi-callback = #(lambda (grob)
1426 (grob-interpret-markup grob (markup "fulanito")))
1430 @node Código de Scheme en línea
1431 @section Código de Scheme en línea
1432 @translationof Inline Scheme code
1434 La principal desventaja de @code{\tweak} es su inflexibilidad
1435 sintáctica. Por ejemplo, lo siguiente produce un error de sintaxis (o
1436 más bien: así lo hacía en algún momento del pasado):
1439 F = \tweak font-size #-3 -\flageolet
1447 Usando Scheme, se puede dar un rodeo a este problema. La ruta hacia
1448 el resultado se da en @ref{Añadir articulaciones a las notas
1449 (ejemplo)}, especialmente cómo usar @code{\displayMusic} como guía de
1453 F = #(let ((m (make-music 'ArticulationEvent
1454 'articulation-type "flageolet")))
1455 (set! (ly:music-property m 'tweaks)
1456 (acons 'font-size -3
1457 (ly:music-property m 'tweaks)))
1466 Aquí, las propiedades @code{tweaks} del objeto flageolet @code{m}
1467 (creado con @code{make-music}) se extraen con
1468 @code{ly:music-property}, se antepone un nuevo par clave-valor para
1469 cambiar el tamaño de la tipografía a la lista de propiedades con la
1470 función de Scheme @code{acons}, y finalmente el resultado se escribe
1471 de nuevo con @code{set!}. El último elemento del bloque @code{let} es
1472 el valor de retorno, el propio @code{m}.
1475 @node Trucos difíciles
1476 @section Trucos difíciles
1477 @translationof Difficult tweaks
1479 Hay un cierto número de tipos de ajustes difíciles.
1485 Un tipo de ajuste difícil es la apariencia de los objetos de
1486 extensión, como las ligaduras de expresión y de unión. Inicialmente,
1487 sólo se crea uno de estos objetos, y pueden ajustarse con el mecanismo
1488 normal. Sin embargo, en ciertos casos los objetos extensores cruzan
1489 los saltos de línea. Si esto ocurre, estos objetos se clonan. Se
1490 crea un objeto distinto por cada sistema en que se encuentra. Éstos
1491 son clones del objeto original y heredan todas sus propiedades,
1492 incluidos los @code{\override}s.
1494 En otras palabras, un @code{\override} siempre afecta a todas las
1495 piezas de un objeto de extensión fragmentado. Para cambiar sólo una
1496 parte de un extensor en el salto de línea, es necesario inmiscuirse en
1497 el proceso de formateado. El @emph{callback}
1498 @code{after-line-breaking} contiene el procedimiento Scheme que se
1499 llama después de que se han determinado los saltos de línea, y los
1500 objetos de presentación han sido divididos sobre los distintos
1503 En el ejemplo siguiente, definimos un procedimiento
1504 @code{my-callback}. Este procedimiento
1508 determina si hemos sido divididos por los saltos de línea
1510 en caso afirmativo, reúne todos los objetos divididos
1512 comprueba si somos el último de los objetos divididos
1514 en caso afirmativo, establece @code{extra-offset}.
1517 Este procedimiento se instala en @rinternals{Tie} (ligadura de unión),
1518 de forma que la última parte de la ligadura dividida se traslada hacia
1521 @lilypond[quote,verbatim,ragged-right]
1522 #(define (my-callback grob)
1524 ;; have we been split?
1525 (orig (ly:grob-original grob))
1527 ;; if yes, get the split pieces (our siblings)
1528 (siblings (if (ly:grob? orig)
1529 (ly:spanner-broken-into orig)
1532 (if (and (>= (length siblings) 2)
1533 (eq? (car (last-pair siblings)) grob))
1534 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1537 \override Tie.after-line-breaking =
1545 Al aplicar este truco, la nueva función de callback
1546 @code{after-line-breaking} también debe llamar a la antigua,
1547 si existe este valor predeterminado. Por ejemplo, si se usa con
1548 @code{Hairpin}, se debe llamar también a
1549 @code{ly:spanner::kill-zero-spanned-time}.
1552 @item Algunos objetos no se pueden cambiar con @code{\override} por
1553 razones técnicas. Son ejemplos @code{NonMusicalPaperColumn} y
1554 @code{PaperColumn}. Se pueden cambiar con la función
1555 @code{\overrideProperty} que funciona de forma similar a @code{\once
1556 \override}, pero usa una sintaxis distinta.
1560 Score.NonMusicalPaperColumn % Nombre del grob
1561 . line-break-system-details % Nombre de la propiedad
1562 . next-padding % Nombre de la subpropiedad, opcional
1566 Observe, sin embargo, que @code{\override}, aplicado a
1567 @code{NonMusicalPaperColumn} y a @code{PaperColumn}, aún funciona
1568 como se espera dentro de los bloques @code{\context}.
1573 @node Interfaces de Scheme de LilyPond
1574 @chapter Interfaces de Scheme de LilyPond
1575 @translationof LilyPond Scheme interfaces
1577 Este capítulo cubre las diversas herramientas proporcionadas por
1578 LilyPond como ayuda a los programadores de Scheme a extraer e
1579 introducir información de los flujos musicales.
1581 HACER @c TODO -- figure out what goes in here and how to organize it