1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: es -*-
2 @c This file is part of extending.tely
4 Translation of GIT committish: 5616bc8f6dc0d17d2d3d669ee0faf4309dde6c78
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 * Funciones musicales::
23 * Funciones de marcado::
24 * Contextos para programadores::
25 * Funciones de callback::
26 * Código de Scheme en línea::
30 @node Funciones musicales
31 @section Funciones musicales
32 @translationof Music functions
34 Las funciones musicales son funciones de Scheme que se utilizan para
35 crear automáticamente expresiones musicales. Se pueden usar para
36 simplificar enormemente el archivo de entrada.
39 * Sintaxis de las funciones musicales::
40 * Funciones de sustitución sencillas::
41 * Funciones de sustitución intermedias::
42 * Matemáticas dentro de las funciones::
44 * Funciones sin argumentos::
47 @node Sintaxis de las funciones musicales
48 @subsection Sintaxis de las funciones musicales
49 @translationof Music function syntax
51 La sintaxis general de una función musical es:
55 #(define-music-function (parser location @var{var_1} @var{var_2}...@var{var_n})
56 (@var{var_1-type?} @var{var_2-type?}...@var{var_n-type?})
57 @var{...expresión musical válida...})
63 @multitable @columnfractions .33 .66
64 @item @var{var_i} @tab @var{i}-ésima variable
65 @item @var{var_i-type?} @tab tipo de la @var{i}-ésima variable
66 @item @var{...expresión musical válida...} @tab expresión que devuelve
67 música válida, generalmente en la forma de una expresión de Scheme.
68 También hay una sintaxis especial que permite la existencia de código
69 de entrada de LilyPond dentro de esta expresión musical.
72 Los comprobadores de tipo de variable son procedimientos de Scheme que
73 devuelven @code{#t} si una variable es de un tipo dado. Se muestran
74 algunos tipos comunes en la tabla de abajo. Hay más tipos en los
75 archivos @file{lily/music-scheme.cc} y @file{scm/c++.scm}.
77 @multitable @columnfractions .33 .66
78 @headitem Tipo de entrada @tab notación de @var{vari-type?}
79 @item Entero @tab @code{integer?}
80 @item Flotante (número decimal) @tab @code{number?}
81 @item Cadena de texto @tab @code{string?}
82 @item Marcado @tab @code{markup?}
83 @item Expresión musical @tab @code{ly:music?}
84 @item Pareja de variables @tab @code{pair?}
87 Los argumentos @code{parser} y @code{location} son obligatorios. El
88 argumento @code{parser} se usa en el cuerpo de la función para tener
89 acceso al valor de otra variable de LilyPond. El argumento
90 @code{location} se usa para establecer el @q{origen} de la expresión
91 musical que se construye por parte de la función musical, de forma que
92 en caso de un error de sintaxis LilyPond pueda comunicar al usuario el
93 lugar adecuado del archivo de entrada en que buscar.
96 @node Funciones de sustitución sencillas
97 @subsection Funciones de sustitución sencillas
98 @translationof Simple substitution functions
100 Una función de sustitución sencilla es una función musical cuya
101 expresión musical de salida está escrita en código de LilyPond, pero
102 con una variable de entrada sustituida en el código de LilyPond. La
103 forma general de estas funciones es:
107 #(define-music-function (parser location @var{var1})
110 @emph{... código de entrada de LilyPond con} @code{#$var1} @emph{para sustituir ...}
114 Observe que los caracteres especiales @code{#@{} y @code{#@}}
115 encierran la música de LilyPond.
117 @multitable @columnfractions .33 .66
118 @item @var{vari} @tab @var{i}-ésima variable
119 @item @var{vari-type?} @tab tipo de la @var{i}-ésima variable
120 @item @var{...música...} @tab código de entrada normal de LilyPond, que utiliza variables como @code{#$var1}, etc.
123 Por ejemplo, se puede definir una función que simplifique el
124 establecimiento de un relleno para un guión de texto TextScript:
126 @lilypond[quote,verbatim,ragged-right]
127 padText = #(define-music-function (parser location padding) (number?)
129 \once \override TextScript #'padding = #$padding
137 c4^"piu mosso" fis a g
141 Además de números, podemos usar expresiones musicales, como por
142 ejemplo notas, como argumentos de las funciones musicales:
144 @lilypond[quote,verbatim,ragged-right]
145 custosNote = #(define-music-function (parser location note)
148 \once \override Voice.NoteHead #'stencil =
149 #ly:text-interface::print
150 \once \override Voice.NoteHead #'text =
151 \markup \musicglyph #"custodes.mensural.u0"
152 \once \override Voice.Stem #'stencil = ##f
158 @node Funciones de sustitución intermedias
159 @subsection Funciones de sustitución intermedias
160 @translationof Intermediate substitution functions
162 Algo más complicadas que las funciones de sustitución sencillas, las
163 funciones de sustitución intermedias contienen una mezcla de código de
164 Scheme y de LilyPond dentro de la expresión musical que se devuelve.
166 Algunas instrucciones @code{\override} requieren un argumento que
167 consiste en una pareja de números (llamada una @code{célula cons} en
170 La pareja se puede pasar directamente dentro de la función musical,
171 usando una variable @code{pair?}:
176 #(define-music-function (parser location principio-final)
179 \once \override Beam #'positions = #$principio-final
183 \barraManual #'(3 . 6) c8 d e f
188 De forma alternativa, los números que componen la pareja se pueden
189 pasar como argumentos separados, y el código de Scheme que se ha usado
190 para crear la pareja se puede incluir dentro de la expresión musical:
192 @lilypond[quote,verbatim,ragged-right]
194 #(define-music-function (parser location beg end)
197 \once \override Beam #'positions = #(cons $beg $end)
201 \manualBeam #3 #6 c8 d e f
206 @node Matemáticas dentro de las funciones
207 @subsection Matemáticas dentro de las funciones
208 @translationof Mathematics in functions
210 Las funciones musicales pueden contar con programación de Scheme
211 además de la simple sustitución:
213 @lilypond[quote,verbatim,ragged-right]
214 AltOn = #(define-music-function (parser location mag) (number?)
215 #{ \override Stem #'length = #$(* 7.0 mag)
216 \override NoteHead #'font-size =
217 #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag))) #})
220 \revert Stem #'length
221 \revert NoteHead #'font-size
224 { c'2 \AltOn #0.5 c'4 c'
225 \AltOn #1.5 c' c' \AltOff c'2 }
229 Este ejemplo se puede reescribir de forma que pase expresiones
232 @lilypond[quote,verbatim,ragged-right]
233 withAlt = #(define-music-function (parser location mag music) (number? ly:music?)
234 #{ \override Stem #'length = #$(* 7.0 mag)
235 \override NoteHead #'font-size =
236 #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
238 \revert Stem #'length
239 \revert NoteHead #'font-size #})
241 { c'2 \withAlt #0.5 {c'4 c'}
242 \withAlt #1.5 {c' c'} c'2 }
246 @node Funciones vacías
247 @subsection Funciones vacías
248 @translationof Void functions
250 Una función musical debe devolver una expresión musical, pero a veces
251 podemos necesitar una función en la que no hay música en juego (como
252 la desactivación de la funcionalidad Apuntar y Pulsar). Para hacerlo,
253 devolvemos una expresión musical @code{void} (vacía).
255 Este es el motivo por el que la forma que se devuelve es
256 @code{(make-music ...)}. Con el valor de la propiedad @code{'void}
257 establecido a @code{#t}, le decimos al analizador que descarte la
258 expresión musical devuelta. así, la parte importante de la función
259 musical vacía es el proceso realizado por la función, no la expresión
260 musical que se devuelve.
264 #(define-music-function (parser location) ()
265 (ly:set-option 'point-and-click #f)
266 (make-music 'SequentialMusic 'void #t))
268 \noApuntarYPulsar % desactivar la funcionalidad Apuntar y Pulsar.
272 @node Funciones sin argumentos
273 @subsection Funciones sin argumentos
274 @translationof Functions without arguments
276 En casi todos los casos, una función sin argumentos se debe escribir
280 dolce = \markup@{ \italic \bold dolce @}
283 Sin embargo, en raras ocasiones puede ser de utilidad crear una
284 función musical sin argumentos:
287 mostrarNumeroDeCompas =
288 #(define-music-function (parser location) ()
289 (if (eq? #t (ly:get-option 'display-bar-numbers))
290 #@{ \once \override Score.BarNumber #'break-visibility = ##f #@}
294 Para la impresión real de los números de compás donde se llama a esta
295 función, invoque a @command{lilypond} con
298 lilypond -d display-bar-numbers ARCHIVO.ly
302 @node Funciones de marcado
303 @section Funciones de marcado
304 @translationof Markup functions
306 Los elementos de marcado están implementados como funciones de Scheme
307 especiales que producen un objeto @code{Stencil} dada una serie de
312 * Construcción de elementos de marcado en Scheme::
313 * Cómo funcionan internamente los elementos de marcado::
314 * Definición de una instrucción de marcado nueva::
315 * Definición de nuevas instrucciones de lista de marcado::
318 @node Construcción de elementos de marcado en Scheme
319 @subsection Construcción de elementos de marcado en Scheme
320 @translationof Markup construction in Scheme
322 @cindex marcado, definir instrucciones de
324 El macro @code{markup} construye expresiones de marcado en Scheme,
325 proporcionando una sintaxis similar a la de LilyPond. Por ejemplo:
328 (markup #:column (#:line (#:bold #:italic "hola" #:raise 0.4 "mundo")
329 #:larger #:line ("fulano" "fulanito" "menganito")))
335 \markup \column @{ \line @{ \bold \italic "hola" \raise #0.4 "mundo" @}
336 \larger \line @{ fulano fulanito menganito @} @}
340 Este ejemplo muestra las principales reglas de traducción entre la
341 sintaxis del marcado normal de LilyPond y la sintaxis del marcado de
345 @multitable @columnfractions .3 .3
346 @item @b{LilyPond} @tab @b{Scheme}
347 @item @code{\markup marcado1} @tab @code{(markup marcado1)}
348 @item @code{\markup @{ marcado1 marcado2 ... @}} @tab
349 @code{(markup marcado1 marcado2 ... )}
350 @item @code{\instruccion} @tab @code{#:instruccion}
351 @item @code{\variable} @tab @code{variable}
352 @item @code{\center-column @{ ... @}} @tab @code{#:center-column ( ... )}
353 @item @code{cadena} @tab @code{"cadena"}
354 @item @code{#argumento-de-scheme} @tab @code{argumento-de-scheme}
358 Todo el lenguaje Scheme está accesible dentro del macro @code{markup}.
359 Por ejemplo, podemos usar llamadas a funciones dentro de @code{markup}
360 para así manipular cadenas de caracteres. Esto es útil si se están
361 definiendo instrucciones de marcado nuevas (véase @ref{Definición de una instrucción de marcado nueva}).
366 El argumento markup-list de instrucciones como @code{#:line},
367 @code{#:center} y @code{#:column} no puede ser una variable ni el
368 resultado de la llamada a una función.
371 (markup #:line (funcion-que-devuelve-marcados))
375 no es válido. Hay que usar las funciones @code{make-line-markup},
376 @code{make-center-markup} o @code{make-column-markup} en su lugar:
379 (markup (make-line-markup (funcion-que-devuelve-marcados)))
383 @node Cómo funcionan internamente los elementos de marcado
384 @subsection Cómo funcionan internamente los elementos de marcado
385 @translationof How markups work internally
387 En un elemento de marcado como
390 \raise #0.5 "ejemplo de texto"
394 @code{\raise} se representa en realidad por medio de la función
395 @code{raise-markup}. La expresión de marcado se almacena como
398 (list raise-markup 0.5 (list simple-markup "ejemplo de texto"))
401 Cuando el marcado se convierte en objetos imprimibles (Stencils o
402 sellos), se llama la función @code{raise-markup} como
406 @var{\objeto de marcado}
407 @var{lista de listas asociativas de propiedades}
409 @var{el marcado "ejemplo de texto"})
412 Primero la función @code{raise-markup} crea el sello para la cadena
413 @code{ejemplo de texto}, y después eleva el sello Stencil en 0.5
414 espacios de pentagrama. Este es un ejemplo bastante simple; en el
415 resto de la sección podrán verse ejemplos más complejos, así como en
416 @file{scm/@/define@/-markup@/-commands@/.scm}.
419 @node Definición de una instrucción de marcado nueva
420 @subsection Definición de una instrucción de marcado nueva
421 @translationof New markup command definition
423 Esta sección trata sobre la definición de nuevas instrucciones de
428 * Sintaxis de la definición de instrucciones de marcado::
429 * Acerca de las propiedades::
430 * Un ejemplo completo::
431 * Adaptación de instrucciones incorporadas::
434 @node Sintaxis de la definición de instrucciones de marcado
435 @unnumberedsubsubsec Sintaxis de la definición de instrucciones de marcado
436 @translationof Markup command definition syntax
438 Se pueden definir instrucciones de marcado nuevas usando el macro de
439 Scheme @code{define-markup-command}, en el nivel sintáctico superior.
442 (define-markup-command (@var{nombre-de-la-instruccion} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
443 (@var{tipo-de-arg1?} @var{tipo-de-arg2?} ...)
444 [ #:properties ((@var{propiedad1} @var{valor-predeterminado1})
452 @item nombre-de-la-instruccion
453 nombre de la instrucción de marcado
455 la definición de @q{layout} (disposición).
457 una lista de listas asociativas, que contienen todas las propiedades
460 argumento @var{i}-ésimo de la instrucción
462 predicado de tipo para el argumento @var{i}-ésimo
465 Si la instrucción utiliza propiedades de los argumentos @var{props},
466 se puede usar la palabra clave @code{#:properties} para especificar
467 qué propiedades se usan, y sus valores predeterminados.
470 Existen algunas restricciones sobre los argumentos posibles de una
471 instrucción de marcado.
473 Los argumentos se distinguen según su tipo:
475 @item un marcado, que corresponde al predicado de tipo @code{markup?};
476 @item una lista de marcados, que corresponde al predicado de tipo
478 @item cualquier otro objeto de Scheme, que corresponde a predicados de tipo como
479 @code{list?}, @code{number?}, @code{boolean?}, etc.
482 Actualmente las combinaciones de argumentos que hay disponibles
483 (después de los argumentos estándar @var{layout} y @var{props}) para
484 una instrucción de marcado definida con @code{define-markup-command}
485 se limitan a la siguiente lista:
488 @item (sin argumentos)
489 @itemx @var{markup-list}
491 @itemx @var{markup markup}
493 @itemx @var{scheme markup}
494 @itemx @var{scheme scheme}
495 @itemx @var{scheme scheme markup}
496 @itemx @var{scheme scheme markup markup}
497 @itemx @var{scheme markup markup}
498 @itemx @var{scheme scheme scheme}
502 Esto significa que no es posible definir con p.ej. tres argumentos de
503 Scheme y un argumento de marcado, como:
506 #(define-markup-command (fulanito layout props
507 num1 num2 lista marcado)
508 (number? number? list? markup?)
513 Si la aplicamos como, digamos,
516 \markup \fulanito #1 #2 #'(mengano zutano) Loquesea
519 @cindex firma de Scheme
520 @cindex Scheme, firma de
522 @command{lilypond} protesta diciendo que no puede analizar
523 @code{fulanito} debido a su firma de Scheme desconocida.
526 @node Acerca de las propiedades
527 @unnumberedsubsubsec Acerca de las propiedades
528 @translationof On properties
530 Los argumentos @code{layout} y @code{props} de las instrucciones de
531 marcado traen a escena un contexto para la interpretación del marcado:
532 tamaño de la tipografía, grueso de línea, etc.
534 El argumento @code{layout} permite el acceso a las propiedades
535 definidas en los bloques @code{paper}, usando la función
536 @code{ly:output-def-lookup}. Por ejemplo, el grueso de línea (el
537 mismo que el que se usa en las partituras) se lee usando:
540 (ly:output-def-lookup layout 'line-width)
543 El argumento @code{props} hace accesibles algunas propiedades a las
544 instrucciones de marcado. Por ejemplo, cuando se interpreta el
545 marcado del título de un libro, todas las variables definidas dentro
546 del bloque @code{\header} se añaden automáticamente a @code{props}, de
547 manera que el marcado del título del libro puede acceder al título del
548 libro, el autor, etc. También es una forma de configurar el
549 comportamiento de una instrucción de marcado: por ejemplo, cuando una
550 instrucción utiliza tamaños de tipografía durante el procesado, el
551 tamaño se lee de @code{props} en vez de tener un argumento
552 @code{font-size}. El que llama a una instrucción de marcado puede
553 cambiar el valor de la propiedad del tamaño de la tipografía con el
554 objeto de modificar el comportamiento. Utilice la palabra clave
555 @code{#:properties} de @code{define-markup-command} para especificar
556 qué propiedades se deben leer a partir de los argumentos de
559 El ejemplo de la sección siguiente ilustra cómo acceder y
560 sobreescribir las propiedades de una instrucción de marcado.
563 @node Un ejemplo completo
564 @unnumberedsubsubsec Un ejemplo completo
565 @translationof A complete example
567 El ejemplo siguiente define una instrucción de marcado para trazar un
568 rectángulo doble alrededor de un fragmento de texto.
570 En primer lugar, necesitamos construir un resultado aproximado
571 utilizando marcados. Una consulta a @ruser{Text markup commands} nos
572 muestra que es útil la instrucción @code{\box}:
574 @lilypond[quote,verbatim,ragged-right]
575 \markup \box \box HELLO
578 Ahora, consideramos que es preferible tener más separación entre el
579 texto y los rectángulos. Según la documentación de @code{\box}, esta
580 instrucción usa una propiedad @code{box-padding}, cuyo valor
581 predeterminado es 0.2. La documentación también menciona cómo
582 sobreescribir este valor:
584 @lilypond[quote,verbatim,ragged-right]
585 \markup \box \override #'(box-padding . 0.6) \box A
588 Después, el relleno o separación entre los dos rectángulos nos parece
589 muy pequeño, así que lo vamos a sobreescribir también:
591 @lilypond[quote,verbatim,ragged-right]
592 \markup \override #'(box-padding . 0.4) \box \override #'(box-padding . 0.6) \box A
595 Repetir esta extensa instrucción de marcado una y otra vez sería un
596 quebradero de cabeza. Aquí es donde se necesita una instrucción de
597 marcado. Así pues, escribimos una instrucción de marcado
598 @code{double-box}, que toma un argumento (el texto). Dibuja los dos
599 rectángulos y añade una separación.
602 #(define-markup-command (double-box layout props text) (markup?)
603 "Trazar un rectángulo doble rodeando el texto."
604 (interpret-markup layout props
605 (markup #:override '(box-padding . 0.4) #:box
606 #:override '(box-padding . 0.6) #:box text)))
609 @code{text} es el nombre del argumento de la instrucción, y
610 @code{markup?} es el tipo: lo identifica como un elemento de marcado.
611 La función @code{interpret-markup} se usa en casi todas las
612 instrucciones de marcado: construye un sello, usando @code{layout},
613 @code{props}, y un elemento de marcado. Aquí, la marca se construye
614 usando el macro de Scheme @code{markup}, véase @ref{Construcción de
615 elementos de marcado en Scheme}. La transformación de una expresión
616 @code{\markup} en una expresión de marcado de Scheme es directa.
618 La instrucción nueva se puede usar como sigue:
621 \markup \double-box A
624 Sería buen hacer que la instrucción @code{double-box} fuera
625 personalizable: aquí, los valores de relleno @code{box-padding} son
626 fijos, y no se pueden cambiar por parte del usuario. Además, sería
627 mejor distinguir la separación entre los dos rectángulos, del relleno
628 entre el rectángulo interno y el texto. Así pues, introducimos una
629 nueva propiedad, @code{inter-box-padding}, para el relleno entre los
630 rectángulos. El @code{box-padding} se usará para el relleno interno.
631 Ahora el código nuevo es como se ve a continuación:
634 #(define-markup-command (double-box layout props text) (markup?)
635 #:properties ((inter-box-padding 0.4)
637 "Trazar un rectángulo doble rodeando el texto."
638 (interpret-markup layout props
639 (markup #:override `(box-padding . ,inter-box-padding) #:box
640 #:override `(box-padding . ,box-padding) #:box text)))
643 Aquí, la palabra clave @code{#:properties} se usa de manera que las
644 propiedades @code{inter-box-padding} y @code{box-padding} se leen a
645 partir del argumento @code{props}, y se les proporcionan unos valores
646 predeterminados si las propiedades no están definidas.
648 Después estos valores se usan para sobreescribir las propiedades
649 @code{box-padding} usadas por las dos instrucciones @code{\box}.
650 Observe el apóstrofo invertido y la coma en el argumento de
651 @code{\override}: nos permiten introducir un valor de variable dentro
652 de una expresión literal.
654 Ahora, la instrucción se puede usar dentro de un elemento de marcado,
655 y el relleno de los rectángulos se puede personalizar:
657 @lilypond[quote,verbatim,ragged-right]
658 #(define-markup-command (double-box layout props text) (markup?)
659 #:properties ((inter-box-padding 0.4)
661 "Draw a double box around text."
662 (interpret-markup layout props
663 (markup #:override `(box-padding . ,inter-box-padding) #:box
664 #:override `(box-padding . ,box-padding) #:box text)))
666 \markup \double-box A
667 \markup \override #'(inter-box-padding . 0.8) \double-box A
668 \markup \override #'(box-padding . 1.0) \double-box A
672 @node Adaptación de instrucciones incorporadas
673 @unnumberedsubsubsec Adaptación de instrucciones incorporadas
674 @translationof Adapting builtin commands
676 Una buena manera de comenzar a escribir una instrucción de marcado
677 nueva, es seguir el ejemplo de otra instrucción ya incorporada. Casi
678 todas las instrucciones de marcado que están incorporadas en LilyPond
679 se pueden encontrar en el archivo
680 @file{scm/@/define@/-markup@/-commands@/.scm}.
682 Por ejemplo, querríamos adaptar la instrucción @code{\draw-line}, para
683 que trace una línea doble. La instrucción @code{\draw-line} está
684 definida como sigue (se han suprimido los comentarios de
688 (define-markup-command (draw-line layout props dest)
691 #:properties ((thickness 1))
692 "...documentación..."
693 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
697 (make-line-stencil th 0 0 x y)))
700 Para definir una instrucción nueva basada en otra existente, copie la
701 definición y cámbiele el nombre. La palabra clave @code{#:category}
702 se puede eliminar sin miedo, pues sólo se utiliza para generar
703 documentación de LilyPond, y no tiene ninguna utilidad para las
704 instrucciones de marcado definidas por el usuario.
707 (define-markup-command (draw-double-line layout props dest)
709 #:properties ((thickness 1))
710 "...documentación..."
711 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
715 (make-line-stencil th 0 0 x y)))
718 A continuación se añade una propiedad para establecer la separación
719 entre las dos líneas, llamada @code{line-gap}, con un valor
720 predeterminado de p.ej. 0.6:
723 (define-markup-command (draw-double-line layout props dest)
725 #:properties ((thickness 1)
727 "...documentación..."
731 Finalmente, se añade el código para trazar las dos líneas. Se usan
732 dos llamadas a @code{make-line-stencil} para trazar las líneas, y los
733 sellos resultantes se combinan usando @code{ly:stencil-add}:
735 @lilypond[quote,verbatim,ragged-right]
736 #(define-markup-command (my-draw-line layout props dest)
738 #:properties ((thickness 1)
741 (let* ((th (* (ly:output-def-lookup layout 'line-thickness)
746 (x (cond ((= dx 0) w)
748 (else (/ w (sqrt (+ 1 (* (/ dx dy) (/ dx dy))))))))
749 (y (* (if (< (* dx dy) 0) 1 -1)
752 (else (/ w (sqrt (+ 1 (* (/ dy dx) (/ dy dx))))))))))
753 (ly:stencil-add (make-line-stencil th x y (+ dx x) (+ dy y))
754 (make-line-stencil th (- x) (- y) (- dx x) (- dy y)))))
756 \markup \my-draw-line #'(4 . 3)
757 \markup \override #'(line-gap . 1.2) \my-draw-line #'(4 . 3)
761 @node Definición de nuevas instrucciones de lista de marcado
762 @subsection Definición de nuevas instrucciones de lista de marcado
763 @translationof New markup list command definition
765 Las instrucciones de listas de marcado se definen con el macro de
766 Scheme @code{define-markup-list-command}, que es similar al macro
767 @code{define-markup-command} descrito en @ref{Definición de una
768 instrucción de marcado nueva}, excepto que donde éste devuelve un
769 sello único, aquél devuelve una lista de sellos.
771 En el siguiente ejemplo se define una instrucción de lista de marcado
772 @code{\paragraph}, que devuelve una lista de líneas justificadas,
773 estando la primera de ellas sangrada. La anchura del sangrado se toma
774 del argumento @code{props}.
777 #(define-markup-list-command (paragraph layout props args) (markup-list?)
778 #:properties ((par-indent 2))
779 (interpret-markup-list layout props
780 (make-justified-lines-markup-list (cons (make-hspace-markup par-indent)
784 Aparte de los argumentos usuales @code{layout} y @code{props}, la
785 instrucción de lista de marcados @code{paragraph} toma un argumento de
786 lista de marcados, llamado @code{args}. El predicado para listas de
787 marcados es @code{markup-list?}.
789 En primer lugar, la función toma el ancho del sangrado, una propiedad
790 llamada aquí @code{par-indent}, de la lista de propiedades
791 @code{props}. Si no se encuentra la propiedad, el valor
792 predeterminado es @code{2}. Después, se hace una lista de líneas
793 justificadas usando la función
794 @code{make-justified-lines-markup-list}, que está relacionada con la
795 instrucción incorporada de lista de marcados @code{\justified-lines}.
796 Se añade un espacio horizontal al principio usando la función
797 @code{make-hspace-markup}. Finalmente, la lista de marcados se
798 interpreta usando la función @code{interpret-markup-list}.
800 Esta nueva instrucción de lista de marcados se puede usar como sigue:
805 El arte de la tipografía musical se llama \italic @{grabado (en plancha).@}
806 El término deriva del proceso tradicional de impresión de música.
807 hace sólo algunas décadas, las partituras se hacían cortando y estampando
808 la música en una plancha de zinc o lata en una imagen invertida.
810 \override-lines #'(par-indent . 4) \paragraph @{
811 La plancha se tenía que entintar, y las depresiones causadas por los cortes
812 y estampados retienen la tinta. Se formaba una imagen presionando el papel
813 contra la plancha. El estampado y cortado se hacía completamente
820 @node Contextos para programadores
821 @section Contextos para programadores
822 @translationof Contexts for programmers
825 * Evaluación de contextos::
826 * Ejecutar una función sobre todos los objetos de la presentación::
829 @node Evaluación de contextos
830 @subsection Evaluación de contextos
831 @translationof Context evaluation
833 @cindex código, llamadas durante la interpretación
834 @funindex \applyContext
836 Se pueden modificar los contextos durante la interpretación con código
837 de Scheme. La sintaxis para esto es
840 \applyContext @var{función}
843 @var{función} debe ser una función de Scheme que toma un único
844 argumento, que es el contexto al que aplicarla. El código siguiente
845 imprime el número del compás actual sobre la salida estándar durante
851 (format #t "\nSe nos ha llamado en el compás número ~a.\n"
852 (ly:context-property x 'currentBarNumber)))
856 @node Ejecutar una función sobre todos los objetos de la presentación
857 @subsection Ejecutar una función sobre todos los objetos de la presentación
858 @translationof Running a function on all layout objects
860 @cindex código, llamar sobre objetos de presentación
861 @funindex \applyOutput
864 La manera más versátil de realizar el ajuste fino de un objeto es
865 @code{\applyOutput}. Su sintaxis es
868 \applyOutput @var{contexto} @var{proc}
872 donde @var{proc} es una función de Scheme, que toma tres argumentos.
874 Al interpretarse, la función @var{proc} se llama para cada objeto de
875 presentación que se encuentra en el contexto @var{contexto}, con los
876 siguientes argumentos:
879 @item el propio objeto de presentación,
880 @item el contexto en que se creó el objeto de presentación, y
881 @item el contexto en que se procesa @code{\applyOutput}.
885 Además, la causa del objeto de presentación, es decir el objeto o
886 expresión musical que es responsable de haberlo creado, está en la
887 propiedad @code{cause} del objeto. Por ejemplo, para la cabeza de una
888 nota, éste es un evento @rinternals{NoteHead}, y para un objeto
889 @rinternals{Stem} (plica), éste es un objeto @rinternals{Stem}.
890 @c Impossible - changed to Stem --FV
892 He aquí una función que usar para @code{\applyOutput}; borra las
893 cabezas de las notas que están sobre la línea central:
895 @lilypond[quote,verbatim,ragged-right]
896 #(define (blanker grob grob-origin context)
897 (if (and (memq 'note-head-interface (ly:grob-interfaces grob))
898 (eq? (ly:grob-property grob 'staff-position) 0))
899 (set! (ly:grob-property grob 'transparent) #t)))
902 e4 g8 \applyOutput #'Voice #blanker b d2
907 @node Funciones de callback
908 @section Funciones de callback
909 @translationof Callback functions
911 Las propiedades (como @code{thickness} (grosor), @code{direction}
912 (dirección), etc.) se pueden establecer a valores fijos con \override,
916 \override Stem #'thickness = #2.0
919 Las propiedades pueden fijarse también a un procedimiento de scheme,
921 @lilypond[fragment,verbatim,quote,relative=2]
922 \override Stem #'thickness = #(lambda (grob)
923 (if (= UP (ly:grob-property grob 'direction))
930 En este caso, el procedimiento se ejecuta tan pronto como el valor de
931 la propiedad se reclama durante el proceso de formateo.
933 Casi todo el motor de tipografiado está manejado por estos
934 @emph{callbacks}. Entre las propiedades que usan normalmente
935 @emph{callbacks} están
939 La rutina de impresión, que construye un dibujo para el símbolo
941 La rutina que establece la posición horizontal
943 La rutina que calcula la anchura de un objeto
946 El procedimiento siempre toma un argumento único, que es el grob (el
949 Si se deben llamar rutinas con varios argumentos, el grob actual se
950 puede insertar con una cerradura de grob. He aquí un ajuste
951 procedente de @code{AccidentalSuggestion},
955 ,(ly:make-simple-closure
957 ,(ly:make-simple-closure
958 (list ly:self-alignment-interface::centered-on-x-parent))
959 ,(ly:make-simple-closure
960 (list ly:self-alignment-interface::x-aligned-on-self)))))
964 En este ejemplo, tanto
965 @code{ly:self-alignment-interface::x-aligned-on-self} como
966 @code{ly:self-alignment-interface::centered-on-x-parent} se llaman con
967 el grob como argumento. El resultado se añade con la función
968 @code{+}. Para asegurar que esta adición se ejecuta adecuadamente,
969 todo ello se encierra dentro de @code{ly:make-simple-closure}.
971 De hecho, usar un solo procedimiento como valor de una propiedad
975 (ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
979 El @code{ly:make-simple-closure} interior aporta el grob como
980 argumento de @var{proc}, el exterior asegura que el resultado de la
981 función es lo que se devuelve, en lugar del objeto
982 @code{simple-closure}.
984 Desde dentro de un callback, el método más fácil para evaluar un
985 elemento de marcado es usar grob-interpret-markup. Por ejemplo:
988 mi-callback = #(lambda (grob)
989 (grob-interpret-markup grob (markup "fulanito")))
993 @node Código de Scheme en línea
994 @section Código de Scheme en línea
995 @translationof Inline Scheme code
997 La principal desventaja de @code{\tweak} es su inflexibilidad
998 sintáctica. Por ejemplo, lo siguiente produce un error de sintaxis.
1001 F = \tweak #'font-size #-3 -\flageolet
1009 En otras palabras, @code{\tweak} no se comporta como una articulación
1010 en cuando a la sintaxis; concretamente, no se puede adjuntar con
1011 @code{^} y @code{_}.
1013 Usando Scheme, se puede dar un rodeo a este problema. La ruta hacia
1014 el resultado se da en @ref{Añadir articulaciones a las notas
1015 (ejemplo)}, especialmente cómo usar @code{\displayMusic} como guía de
1019 F = #(let ((m (make-music 'ArticulationEvent
1020 'articulation-type "flageolet")))
1021 (set! (ly:music-property m 'tweaks)
1022 (acons 'font-size -3
1023 (ly:music-property m 'tweaks)))
1032 Aquí, las propiedades @code{tweaks} del objeto flageolet @code{m}
1033 (creado con @code{make-music}) se extraen con
1034 @code{ly:music-property}, se antepone un nuevo par clave-valor para
1035 cambiar el tamaño de la tipografía a la lista de propiedades con la
1036 función de Scheme @code{acons}, y finalmente el resultado se escribe
1037 de nuevo con @code{set!}. El último elemento del bloque @code{let} es
1038 el valor de retorno, el propio @code{m}.
1041 @node Trucos difíciles
1042 @section Trucos difíciles
1043 @translationof Difficult tweaks
1045 Hay un cierto número de tipos de ajustes difíciles.
1051 Un tipo de ajuste difícil es la apariencia de los objetos de
1052 extensión, como las ligaduras de expresión y de unión. Inicialmente,
1053 sólo se crea uno de estos objetos, y pueden ajustarse con el mecanismo
1054 normal. Sin embargo, en ciertos casos los objetos extensores cruzan
1055 los saltos de línea. Si esto ocurre, estos objetos se clonan. Se
1056 crea un objeto distinto por cada sistema en que se encuentra. Éstos
1057 son clones del objeto original y heredan todas sus propiedades,
1058 incluidos los @code{\override}s.
1060 En otras palabras, un @code{\override} siempre afecta a todas las
1061 piezas de un objeto de extensión fragmentado. Para cambiar sólo una
1062 parte de un extensor en el salto de línea, es necesario inmiscuirse en
1063 el proceso de formateado. El @emph{callback}
1064 @code{after-line-breaking} contiene el procedimiento Scheme que se
1065 llama después de que se han determinado los saltos de línea, y los
1066 objetos de presentación han sido divididos sobre los distintos
1069 En el ejemplo siguiente, definimos un procedimiento
1070 @code{my-callback}. Este procedimiento
1074 determina si hemos sido divididos por los saltos de línea
1076 en caso afirmativo, reúne todos los objetos divididos
1078 comprueba si somos el último de los objetos divididos
1080 en caso afirmativo, establece @code{extra-offset}.
1083 Este procedimiento se instala en @rinternals{Tie} (ligadura de unión),
1084 de forma que la última parte de la ligadura dividida se traslada hacia
1087 @lilypond[quote,verbatim,ragged-right]
1088 #(define (my-callback grob)
1090 ; have we been split?
1091 (orig (ly:grob-original grob))
1093 ; if yes, get the split pieces (our siblings)
1094 (siblings (if (ly:grob? orig)
1095 (ly:spanner-broken-into orig) '() )))
1097 (if (and (>= (length siblings) 2)
1098 (eq? (car (last-pair siblings)) grob))
1099 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1102 \override Tie #'after-line-breaking =
1109 Al aplicar este truco, la nueva función de callback
1110 @code{after-line-breaking} también debe llamar a la antigua
1111 @code{after-line-breaking}, si existe. Por ejemplo, si se usa con
1112 @code{Hairpin}, se debe llamar también a
1113 @code{ly:hairpin::after-line-breaking}.
1116 @item Algunos objetos no se pueden cambiar con @code{\override} por
1117 razones técnicas. Son ejemplos @code{NonMusicalPaperColumn} y
1118 @code{PaperColumn}. Se pueden cambiar con la función
1119 @code{\overrideProperty} que funciona de forma similar a @code{\once
1120 \override}, pero usa una sintaxis distinta.
1124 #"Score.NonMusicalPaperColumn" % Nombre del grob
1125 #'line-break-system-details % Nombre de la propiedad
1126 #'((next-padding . 20)) % Valor
1129 Observe, sin embargo, que @code{\override}, aplicado a
1130 @code{NonMusicalPaperColumn} y a @code{PaperColumn}, aún funciona
1131 como se espera dentro de los bloques @code{\context}.
1136 @node Interfaces de Scheme de LilyPond
1137 @chapter Interfaces de Scheme de LilyPond
1138 @translationof LilyPond Scheme interfaces
1140 Este capítulo cubre las diversas herramientas proporcionadas por
1141 LilyPond como ayuda a los programadores de Scheme a extraer e
1142 introducir información de los flujos musicales.
1144 HACER @c TODO -- figure out what goes in here and how to organize it