1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: es -*-
2 @c This file is part of extending.tely
4 Translation of GIT committish: 2055f35c47a045a50a01ff4dba8524322cfc3b48
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 marcado::
26 * Contextos para programadores::
27 * Funciones de callback::
28 * Código de Scheme en línea::
32 @node Bloques de código de Lilypond
33 @section Bloques de código de Lilypond
34 @translationof Lilypond code blocks
36 Los bloques de código de Lilypond tienen el siguiente aspecto:
38 #@{ @var{código de Lilypond} #@}
40 Se pueden usar en cualquier lugar en el que se pueda escribir código
41 de Scheme: el lector de Scheme en efecto se modifica para que pueda
42 incorporar bloques de código de Lilypond. Mientras se está leyendo el
43 bloque de código de Lilypond, se analiza sintácticamente de forma
44 superficial y se sustituye por una llamada al analizador sintáctico de
45 Lilypond, que funciona en tiempo de ejecución para que interprete el
46 bloque de código de Lilypond.
48 El objeto del análisis superficial es la interpretación de los
49 símbolos @code{$} que se pueden usar para aislar expresiones del
50 contexto léxico de Scheme que les rodea (como variables de @code{let}
51 y parámetros de función). El @code{$} se puede usar de las maneras
56 simplemente pasa un único símbolo @code{$} al analizador de Lilypond.
58 evalúa la forma Scheme en tiempo de ejecución y la analiza como un
59 identificador @code{\forma} en el analizador de Lilypond. Dependiendo
60 del tipo del valor, se puede interpretar como varias entidades
61 sintácticas diferentes.
63 evalúa la forma de Scheme en tiempo de ejecución y analiza su valor
64 como una espresión de Scheme dentro del analizador de LilyPond.
66 las formas que están dentro de expresiones de Scheme y que comienzan
67 por @code{#} se leen y se analizan recursivamente hasta que se
68 encuentran símbolos de @code{$}. Entonces se tratan como sigue:
69 @item #@dots{}$@var{variable}
70 analiza el valor de la variable dentro de la expresión circundante.
71 @item #@dots{}($ @var{forma} @dots{})
72 analiza el valor de la forma dentro de la expresión circundante. Al
73 contrario que las @code{$@var{formas}} a nivel de LilyPond,
74 necesitamos separar la forma con un espacio en blanco, haciendo que
75 @code{$} sea reconocible como un símblo de Scheme separado.
78 Un bloque de código de LilyPond puede contener cualquier cosa que
79 podríamos utilizar en la parte derecha de una asignación. Además, un
80 bloque de LilyPond vacío corresponde a una expresión musical vacía, y
81 un bloque de LilyPond que contiene varios eventos musicales se
82 convierte en una expresión de música secuencial.
84 @node Funciones de Scheme
85 @section Funciones de Scheme
86 @translationof Scheme functions
88 Las @emph{funciones de Scheme} son procedimientos de Scheme que poeden
89 crear expresiones de Scheme a partir de código de entrada escrito en
90 la sintaxis de LilyPond. Se pueden llamar desde prácticamente
91 cualquier lugar en el que se permita el uso de @code{#} para la
92 especificación de un valor en sintaxis de Scheme. Mientras que Scheme
93 tiene funciones propias, este capítulo se ocupa de las funciones
94 @emph{sintácticas}, funciones que reciben argumentos especificados en
95 la sintaxis de LilyPond.
98 * Definición de funciones de Scheme::
99 * Uso de las funciones de Scheme::
100 * Funciones de Scheme vacías::
103 @node Definición de funciones de Scheme
104 @subsection Definición de funciones de Scheme
105 @translationof Scheme function definitions
107 La forma general de la definición de una función de Scheme es:
111 #(define-scheme-function
112 (parser location @var{arg1} @var{arg2} @dots{})
113 (@var{type1?} @var{type2?} @dots{})
120 @multitable @columnfractions .33 .66
121 @item @code{@var{argN}}
122 @tab @var{n}-ésimo argumento
124 @item @code{@var{typeN?}}
125 @tab un @emph{predicado de tipo} de Scheme para el que @code{@var{argN}}
126 debe devolver @code{#t}. Algunos de estos predicados se reconocen de
127 forma especial por parte del analizador, véase más abajo.
129 @item @code{@var{cuerpo}}
130 @tab una secuencia de formas de Scheme que se evalúan ordenadamente; la
131 última forma de la secuencia se usa como el valor de retorno de la
132 función de Scheme. Puede contener bloques de código de LilyPond
133 encerrados entre llaves con almohadillas
134 (@tie{}@w{@code{#@{@dots{}#@}}}@tie{}), como se describe en
135 @ref{Bloques de código de Lilypond}. Dentro de los bloques de código
136 de LilyPond, use el símbolo del dólar @code{$} para hacer referencia a
137 argumentos de función (p.ej. @samp{$arg1}) o para iniciar una
138 expresión en línea de Scheme que contenga argumentos de función
139 (p.ej. @w{@samp{$(cons arg1 arg2)}}).
143 Ciertos predicados de tipo se reconocen de forma especial por parte
144 del analizador sintáctico y hacen que éste busque los argumentos
145 respectivos en la sintaxis de LilyPond en lugar de hacerlo en la
146 sintaxis de Scheme. Actualmente son @code{ly:music?}, @code{markup?},
147 @code{ly:pitch?} y @code{ly:duration?}.
149 Si realmente quiere escribir uno de los elementos especiales como
150 Scheme en lugar de como una expresión de LilyPond, puede escribirlos
151 como una expresión de Scheme que llame a @code{ly:export} en su nivel
154 Otros predicados de tipo, entre ellos los que están definidos por el
155 usuario hacen que el argumento respectivo sólo se acepte como una
156 expresión de Scheme, normalmente precedida de @code{#} o como
157 resultado de llamar a una función de Scheme.
159 Para ver una lista de los predicados de tipo disponibles, consulte
160 @ruser{Predicados de tipo predefinidos}.
164 Referencia de la notación:
165 @ruser{Predicados de tipo predefinidos}.
168 @file{lily/music-scheme.cc},
173 @node Uso de las funciones de Scheme
174 @subsection Uso de las funciones de Scheme
175 @translationof Scheme function usage
177 Las funciones de Scheme se pueden llamar casi desde cualquier lugar en
178 que puede escribirse una expresión de Scheme que comience con la
179 almohadilla@tie{}@code{#}. Llamamos a una función de Scheme
180 escribiendo su nombre precedido de la barra invertida@tie{}@code{\}, y
181 seguido por sus argumentos.
183 Aparte de los lugares en que se requiere un valor de Scheme hay
184 ciertos sitios en que se aceptan expresiones de almohadilla @code{#} y
185 se evalúan por sus efectos secundarios, pero por lo demás se ignoran.
186 Son, mayormente, los lugares en que también sería aceptable colocar
189 Hay ciertos lugares especiales en los que un argumento que corresponde
190 a @code{ly:music?} tiene que ser un identificador musical o bien una
191 expresión musical encerrada dentro de @code{@{}@dots{}@code{@}} o
192 @code{<<}@dots{}@code{>>} de forma explícita, de manera que las
193 duraciones o post-eventos ocionales que posiblemente le sigan no
194 puedan confundirse con argumentos adicionales. Un sitio obvio es
195 antes de un predicado @code{ly:duration?}. Otro es el último
196 argumento de una función de Scheme cuando se utiliza en un lugar en
197 que tales partes opcionales podrían, o no, considerarse como parte del
200 En esos casos raros, tenemos que delimitar nuestros argumentos
201 musicales de forma adecuada para evitar la confusión por parte de
204 @node Funciones de Scheme vacías
205 @subsection Funciones de Scheme vacías
206 @translationof Void scheme functions
208 A veces, una función se ejecuta solamente por sus efectos colaterales.
209 En tal caso, la utilización de una función de Scheme supone que su
210 valor no será considerado de la forma usual:
214 #(define-scheme-function
217 (ly:set-option 'point-and-click #f))
219 \noPointAndClick % desactivar la función de apuntar y pulsar
222 @node Funciones musicales
223 @section Funciones musicales
224 @translationof Music functions
226 Las @emph{funciones musicales} son procedimientos de Scheme que pueden
227 crear automáticamente expresiones musicales, y se pueden usar para
228 simplificar enormemente el archivo de entrada.
231 * Definiciones de funciones musicales::
232 * Uso de las funciones musicales::
233 * Funciones de sustitución sencillas::
234 * Funciones de sustitución intermedias::
235 * Matemáticas dentro de las funciones::
236 * Funciones sin argumentos::
237 * Funciones musicales vacías::
241 @node Definiciones de funciones musicales
242 @subsection Definiciones de funciones musicales
243 @translationof Music function definitions
245 La forma general para definir funciones musicales es:
249 #(define-music-function
250 (parser location @var{arg1} @var{arg2} @dots{})
251 (@var{tipo1?} @var{tipo2?} @dots{})
256 de forma bastante análoga a @ref{Definición de funciones de Scheme}.
257 Lo más probable es que el @var{cuerpo} sea un
258 @ref{Bloques de código de Lilypond,bloque de código de LilyPond}.
260 Para ver una lista de los predicados de tipo disponibles, consulte
261 @ruser{Predicados de tipo predefinidos}.
265 Referencia de la notación:
266 @ruser{Predicados de tipo predefinidos}.
269 @file{lily/music-scheme.cc},
274 @node Uso de las funciones musicales
275 @subsection Uso de las funciones musicales
276 @translationof Music function usage
278 Las funciones musicales se pueden actualmente utilizar en tres
279 lugares. Dependiendo de dónde se usan, son de aplicación ciertas
280 restricciones para que sea posible su anámusicisis sintáctico de forma
281 no ambigua. El resultado que devuelve una función musical debe ser
282 compatible con el contexto desde el que se la llama.
286 At top level in a music expression. There are no special restrictions
287 on the argument list.
290 As a post-event. All trailing arguments of the music function with the
291 predicate @code{ly:music?} will get parsed also as post-events. Note
292 that returning post-events will also be acceptable for music functions
293 called at top level, leading to a result roughly equivalent to
299 As a chord constituent. All trailing arguments of the music function
300 with the predicate @code{ly:music?} will get parsed also as chord
305 The special rules for trailing arguments make it possible to write
306 polymorphic functions like @code{\tweak} that can be applied to
307 different constructs.
309 There is another somewhat special rule: if you have a predicate
310 @code{ly:music?} directly before a @code{ly:duration?} predicate, then
311 the corresponding music expression must be either a music identifier, or
312 literal sequential or parallel music enclosed in
313 @code{@{}@dots{}@code{@}} or @code{<<}@dots{}@code{>>} explicitly.
314 Otherwise, Lilypond could get confused about where the music ends and
317 @node Funciones de sustitución sencillas
318 @subsection Funciones de sustitución sencillas
319 @translationof Simple substitution functions
321 Una función de sustitución sencilla es una función musical cuya
322 expresión musical de salida está escrita en código de LilyPond
323 y contiene argumentos de la función en la expresión de salida.
324 Están descritas en @ruser{Ejemplos de funciones de sustitución}.
327 @node Funciones de sustitución intermedias
328 @subsection Funciones de sustitución intermedias
329 @translationof Intermediate substitution functions
331 Las funciones de sustitución intermedias contienen una
332 mezcla de código de Scheme y de LilyPond
333 dentro de la expresión musical que se devuelve.
335 Algunas instrucciones @code{\override} requieren un argumento que
336 consiste en una pareja de números (llamada una @emph{célula cons} en
339 La pareja se puede pasar directamente dentro de la función musical,
340 usando una variable @code{pair?}:
344 #(define-music-function
345 (parser location principio-final)
348 \once \override Beam #'positions = $principio-final
352 \barraManual #'(3 . 6) c8 d e f
356 De forma alternativa, los números que componen la pareja se pueden
357 pasar como argumentos separados, y el código de Scheme que se ha usado
358 para crear la pareja se puede incluir dentro de la expresión musical:
360 @lilypond[quote,verbatim,ragged-right]
362 #(define-music-function
363 (parser location beg end)
366 \once \override Beam #'positions = $(cons beg end)
370 \manualBeam #3 #6 c8 d e f
375 @node Matemáticas dentro de las funciones
376 @subsection Matemáticas dentro de las funciones
377 @translationof Mathematics in functions
379 Las funciones musicales pueden contar con programación de Scheme
380 además de la simple sustitución:
382 @lilypond[quote,verbatim,ragged-right]
384 #(define-music-function
385 (parser location mag)
388 \override Stem #'length = $(* 7.0 mag)
389 \override NoteHead #'font-size =
390 $(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
394 \revert Stem #'length
395 \revert NoteHead #'font-size
400 \AltOn #1.5 c c \AltOff c2
405 Este ejemplo se puede reescribir de forma que pase expresiones
408 @lilypond[quote,verbatim,ragged-right]
410 #(define-music-function
411 (parser location mag music)
414 \override Stem #'length = $(* 7.0 mag)
415 \override NoteHead #'font-size =
416 $(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
418 \revert Stem #'length
419 \revert NoteHead #'font-size
423 c2 \withAlt #0.5 { c4 c }
424 \withAlt #1.5 { c c } c2
429 @node Funciones sin argumentos
430 @subsection Funciones sin argumentos
431 @translationof Functions without arguments
433 En casi todos los casos, una función sin argumentos se debe escribir
437 dolce = \markup@{ \italic \bold dolce @}
440 Sin embargo, en raras ocasiones puede ser de utilidad crear una
441 función musical sin argumentos:
444 mostrarNumeroDeCompas =
445 #(define-music-function
448 (if (eq? #t (ly:get-option 'display-bar-numbers))
449 #@{ \once \override Score.BarNumber #'break-visibility = ##f #@}
453 Para la impresión real de los números de compás donde se llama a esta
454 función, invoque a @command{lilypond} con
457 lilypond -d display-bar-numbers ARCHIVO.ly
461 @node Funciones musicales vacías
462 @subsection Funciones musicales vacías
463 @translationof Void music functions
465 A music function must return a music expression. If you want to execute
466 a function only for its side effect, it might make more sense to use a
467 scheme function instead. But there may be cases where you sometimes
468 want to produce a music expression, and sometimes not (like in the
469 previous example). Returning a @code{void} music expression via
470 @code{#@{ #@}} will do that.
473 @node Funciones de marcado
474 @section Funciones de marcado
475 @translationof Markup functions
477 Los elementos de marcado están implementados como funciones de Scheme
478 especiales que producen un objeto @code{Stencil} dada una serie de
483 * Construcción de elementos de marcado en Scheme::
484 * Cómo funcionan internamente los elementos de marcado::
485 * Definición de una instrucción de marcado nueva::
486 * Definición de nuevas instrucciones de lista de marcado::
489 @node Construcción de elementos de marcado en Scheme
490 @subsection Construcción de elementos de marcado en Scheme
491 @translationof Markup construction in Scheme
493 @cindex marcado, definir instrucciones de
495 El macro @code{markup} construye expresiones de marcado en Scheme,
496 proporcionando una sintaxis similar a la de LilyPond. Por ejemplo:
499 (markup #:column (#:line (#:bold #:italic "hola" #:raise 0.4 "mundo")
500 #:larger #:line ("fulano" "fulanito" "menganito")))
506 #@{ \markup \column @{ \line @{ \bold \italic "hola" \raise #0.4 "mundo" @}
507 \larger \line @{ fulano fulanito menganito @} @} #@}
511 Este ejemplo muestra las principales reglas de traducción entre la
512 sintaxis del marcado normal de LilyPond y la sintaxis del marcado de
513 Scheme. Using @code{#@{
514 @dots{} #@}} for entering in Lilypond syntax will often be most
515 convenient, but we explain how to use the @code{markup} macro to get a
516 Scheme-only solution.
519 @multitable @columnfractions .3 .3
520 @item @b{LilyPond} @tab @b{Scheme}
521 @item @code{\markup marcado1} @tab @code{(markup marcado1)}
522 @item @code{\markup @{ marcado1 marcado2 ... @}} @tab
523 @code{(markup marcado1 marcado2 ... )}
524 @item @code{\instruccion} @tab @code{#:instruccion}
525 @item @code{\variable} @tab @code{variable}
526 @item @code{\center-column @{ ... @}} @tab @code{#:center-column ( ... )}
527 @item @code{cadena} @tab @code{"cadena"}
528 @item @code{#argumento-de-scheme} @tab @code{argumento-de-scheme}
532 Todo el lenguaje Scheme está accesible dentro del macro @code{markup}.
533 Por ejemplo, podemos usar llamadas a funciones dentro de @code{markup}
534 para así manipular cadenas de caracteres. Esto es útil si se están
535 definiendo instrucciones de marcado nuevas (véase
536 @ref{Definición de una instrucción de marcado nueva}).
541 El argumento markup-list de instrucciones como @code{#:line},
542 @code{#:center} y @code{#:column} no puede ser una variable ni el
543 resultado de la llamada a una función.
546 (markup #:line (funcion-que-devuelve-marcados))
550 no es válido. Hay que usar las funciones @code{make-line-markup},
551 @code{make-center-markup} o @code{make-column-markup} en su lugar:
554 (markup (make-line-markup (funcion-que-devuelve-marcados)))
558 @node Cómo funcionan internamente los elementos de marcado
559 @subsection Cómo funcionan internamente los elementos de marcado
560 @translationof How markups work internally
562 En un elemento de marcado como
565 \raise #0.5 "ejemplo de texto"
569 @code{\raise} se representa en realidad por medio de la función
570 @code{raise-markup}. La expresión de marcado se almacena como
573 (list raise-markup 0.5 (list simple-markup "ejemplo de texto"))
576 Cuando el marcado se convierte en objetos imprimibles (Stencils o
577 sellos), se llama la función @code{raise-markup} como
581 @var{\objeto de marcado}
582 @var{lista de listas asociativas de propiedades}
584 @var{el marcado "ejemplo de texto"})
587 Primero la función @code{raise-markup} crea el sello para la cadena
588 @code{ejemplo de texto}, y después eleva el sello Stencil en 0.5
589 espacios de pentagrama. Este es un ejemplo bastante simple; en el
590 resto de la sección podrán verse ejemplos más complejos, así como en
591 @file{scm/define-markup-commands.scm}.
594 @node Definición de una instrucción de marcado nueva
595 @subsection Definición de una instrucción de marcado nueva
596 @translationof New markup command definition
598 Esta sección trata sobre la definición de nuevas instrucciones de
603 * Sintaxis de la definición de instrucciones de marcado::
604 * Acerca de las propiedades::
605 * Un ejemplo completo::
606 * Adaptación de instrucciones incorporadas::
609 @node Sintaxis de la definición de instrucciones de marcado
610 @unnumberedsubsubsec Sintaxis de la definición de instrucciones de marcado
611 @translationof Markup command definition syntax
613 Se pueden definir instrucciones de marcado nuevas usando el macro de
614 Scheme @code{define-markup-command}, en el nivel sintáctico superior.
617 (define-markup-command (@var{nombre-de-la-instruccion} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
618 (@var{tipo-de-arg1?} @var{tipo-de-arg2?} ...)
619 [ #:properties ((@var{propiedad1} @var{valor-predeterminado1})
627 @item @var{nombre-de-la-instruccion}
628 nombre de la instrucción de marcado
630 la definición de @q{layout} (disposición).
632 una lista de listas asociativas, que contienen todas las propiedades
635 argumento @var{i}-ésimo de la instrucción
636 @item @var{tipo-de-argi?}
637 predicado de tipo para el argumento @var{i}-ésimo
640 Si la instrucción utiliza propiedades de los argumentos @code{props},
641 se puede usar la palabra clave @code{#:properties} para especificar
642 qué propiedades se usan, así como sus valores predeterminados.
644 Los argumentos se distinguen según su tipo:
646 @item un marcado, que corresponde al predicado de tipo @code{markup?};
647 @item una lista de marcados, que corresponde al predicado de tipo
649 @item cualquier otro objeto de Scheme, que corresponde a predicados de tipo como
650 @code{list?}, @code{number?}, @code{boolean?}, etc.
653 No existe ninguna limitación en el orden de los argumentos (después de
654 los argumentos estándar @code{layout} y @code{props}). Sin embargo, las
655 funciones de marcado que toman un elemento de marcado como su último
656 argumento son un poco especiales porque podemos aplicarlas a una lista
657 de marcados y el resultado es una lista de marcados donde la función
658 de marcado (con los argumentos antecedentes especificados) se ha
659 aplicado a todos los elementos de la lista de marcados original.
661 Dado que la replicación de los argumentos precedentes para aplicar una
662 función de marcado a una lista de marcados es poco costosa
663 principalmente por los argumentos de Scheme, se evitan las caídas de
664 reindimiento simplemente mediante la utilización de argumentos de
665 Scheme para los argumentos antecedentes de las funciones de marcado
666 que toman un marcado como su último argumento.
668 @node Acerca de las propiedades
669 @unnumberedsubsubsec Acerca de las propiedades
670 @translationof On properties
672 Los argumentos @code{layout} y @code{props} de las instrucciones de
673 marcado traen a escena un contexto para la interpretación del marcado:
674 tamaño de la tipografía, grueso de línea, etc.
676 El argumento @code{layout} permite el acceso a las propiedades
677 definidas en los bloques @code{paper}, usando la función
678 @code{ly:output-def-lookup}. Por ejemplo, el grueso de línea (el
679 mismo que el que se usa en las partituras) se lee usando:
682 (ly:output-def-lookup layout 'line-width)
685 El argumento @code{props} hace accesibles algunas propiedades a las
686 instrucciones de marcado. Por ejemplo, cuando se interpreta el
687 marcado del título de un libro, todas las variables definidas dentro
688 del bloque @code{\header} se añaden automáticamente a @code{props}, de
689 manera que el marcado del título del libro puede acceder al título del
690 libro, el autor, etc. También es una forma de configurar el
691 comportamiento de una instrucción de marcado: por ejemplo, cuando una
692 instrucción utiliza tamaños de tipografía durante el procesado, el
693 tamaño se lee de @code{props} en vez de tener un argumento
694 @code{font-size}. El que llama a una instrucción de marcado puede
695 cambiar el valor de la propiedad del tamaño de la tipografía con el
696 objeto de modificar el comportamiento. Utilice la palabra clave
697 @code{#:properties} de @code{define-markup-command} para especificar
698 qué propiedades se deben leer a partir de los argumentos de
701 El ejemplo de la sección siguiente ilustra cómo acceder y
702 sobreescribir las propiedades de una instrucción de marcado.
705 @node Un ejemplo completo
706 @unnumberedsubsubsec Un ejemplo completo
707 @translationof A complete example
709 El ejemplo siguiente define una instrucción de marcado para trazar un
710 rectángulo doble alrededor de un fragmento de texto.
712 En primer lugar, necesitamos construir un resultado aproximado
713 utilizando marcados. Una consulta a @ruser{Text markup commands} nos
714 muestra que es útil la instrucción @code{\box}:
716 @lilypond[quote,verbatim,ragged-right]
717 \markup \box \box HELLO
720 Ahora, consideramos que es preferible tener más separación entre el
721 texto y los rectángulos. Según la documentación de @code{\box}, esta
722 instrucción usa una propiedad @code{box-padding}, cuyo valor
723 predeterminado es 0.2. La documentación también menciona cómo
724 sobreescribir este valor:
726 @lilypond[quote,verbatim,ragged-right]
727 \markup \box \override #'(box-padding . 0.6) \box A
730 Después, el relleno o separación entre los dos rectángulos nos parece
731 muy pequeño, así que lo vamos a sobreescribir también:
733 @lilypond[quote,verbatim,ragged-right]
734 \markup \override #'(box-padding . 0.4) \box \override #'(box-padding . 0.6) \box A
737 Repetir esta extensa instrucción de marcado una y otra vez sería un
738 quebradero de cabeza. Aquí es donde se necesita una instrucción de
739 marcado. Así pues, escribimos una instrucción de marcado
740 @code{double-box}, que toma un argumento (el texto). Dibuja los dos
741 rectángulos y añade una separación.
744 #(define-markup-command (double-box layout props text) (markup?)
745 "Trazar un rectángulo doble rodeando el texto."
746 (interpret-markup layout props
747 #@{\markup \override #'(box-padding . 0.4) \box
748 \override #'(box-padding . 0.6) \box @{ $text @}#@}))
754 #(define-markup-command (double-box layout props text) (markup?)
755 "Trazar un rectángulo doble rodeando el texto."
756 (interpret-markup layout props
757 (markup #:override '(box-padding . 0.4) #:box
758 #:override '(box-padding . 0.6) #:box text)))
761 @code{text} es el nombre del argumento de la instrucción, y
762 @code{markup?} es el tipo: lo identifica como un elemento de marcado.
763 La función @code{interpret-markup} se usa en casi todas las
764 instrucciones de marcado: construye un sello, usando @code{layout},
765 @code{props}, y un elemento de marcado. En el segundo caso, la marca
766 se construye usando el macro de Scheme @code{markup}, véase
767 @ref{Construcción de elementos de marcado en Scheme}. La
768 transformación de una expresión @code{\markup} en una expresión de
769 marcado de Scheme es directa.
771 La instrucción nueva se puede usar como sigue:
774 \markup \double-box A
777 Sería buen hacer que la instrucción @code{double-box} fuera
778 personalizable: aquí, los valores de relleno @code{box-padding} son
779 fijos, y no se pueden cambiar por parte del usuario. Además, sería
780 mejor distinguir la separación entre los dos rectángulos, del relleno
781 entre el rectángulo interno y el texto. Así pues, introducimos una
782 nueva propiedad, @code{inter-box-padding}, para el relleno entre los
783 rectángulos. El @code{box-padding} se usará para el relleno interno.
784 Ahora el código nuevo es como se ve a continuación:
787 #(define-markup-command (double-box layout props text) (markup?)
788 #:properties ((inter-box-padding 0.4)
790 "Trazar un rectángulo doble rodeando el texto."
791 (interpret-markup layout props
792 #@{\markup \override #`(box-padding . ,$inter-box-padding) \box
793 \override #`(box-padding . ,$box-padding) \box
797 Again, the equivalent version using the markup macro would be:
800 #(define-markup-command (double-box layout props text) (markup?)
801 #:properties ((inter-box-padding 0.4)
803 "Draw a double box around text."
804 (interpret-markup layout props
805 (markup #:override `(box-padding . ,inter-box-padding) #:box
806 #:override `(box-padding . ,box-padding) #:box text)))
809 Aquí, la palabra clave @code{#:properties} se usa de manera que las
810 propiedades @code{inter-box-padding} y @code{box-padding} se leen a
811 partir del argumento @code{props}, y se les proporcionan unos valores
812 predeterminados si las propiedades no están definidas.
814 Después estos valores se usan para sobreescribir las propiedades
815 @code{box-padding} usadas por las dos instrucciones @code{\box}.
816 Observe el apóstrofo invertido y la coma en el argumento de
817 @code{\override}: nos permiten introducir un valor de variable dentro
818 de una expresión literal.
820 Ahora, la instrucción se puede usar dentro de un elemento de marcado,
821 y el relleno de los rectángulos se puede personalizar:
823 @lilypond[quote,verbatim,ragged-right]
824 #(define-markup-command (double-box layout props text) (markup?)
825 #:properties ((inter-box-padding 0.4)
827 "Draw a double box around text."
828 (interpret-markup layout props
829 #{\markup \override #`(box-padding . ,$inter-box-padding) \box
830 \override #`(box-padding . ,$box-padding) \box
833 \markup \double-box A
834 \markup \override #'(inter-box-padding . 0.8) \double-box A
835 \markup \override #'(box-padding . 1.0) \double-box A
839 @node Adaptación de instrucciones incorporadas
840 @unnumberedsubsubsec Adaptación de instrucciones incorporadas
841 @translationof Adapting builtin commands
843 Una buena manera de comenzar a escribir una instrucción de marcado
844 nueva, es seguir el ejemplo de otra instrucción ya incorporada. Casi
845 todas las instrucciones de marcado que están incorporadas en LilyPond
846 se pueden encontrar en el archivo
847 @file{scm/define-markup-commands.scm}.
849 Por ejemplo, querríamos adaptar la instrucción @code{\draw-line}, para
850 que trace una línea doble. La instrucción @code{\draw-line} está
851 definida como sigue (se han suprimido los comentarios de
855 (define-markup-command (draw-line layout props dest)
858 #:properties ((thickness 1))
859 "...documentación..."
860 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
864 (make-line-stencil th 0 0 x y)))
867 Para definir una instrucción nueva basada en otra existente, copie la
868 definición y cámbiele el nombre. La palabra clave @code{#:category}
869 se puede eliminar sin miedo, pues sólo se utiliza para generar
870 documentación de LilyPond, y no tiene ninguna utilidad para las
871 instrucciones de marcado definidas por el usuario.
874 (define-markup-command (draw-double-line layout props dest)
876 #:properties ((thickness 1))
877 "...documentación..."
878 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
882 (make-line-stencil th 0 0 x y)))
885 A continuación se añade una propiedad para establecer la separación
886 entre las dos líneas, llamada @code{line-gap}, con un valor
887 predeterminado de p.ej. 0.6:
890 (define-markup-command (draw-double-line layout props dest)
892 #:properties ((thickness 1)
894 "...documentación..."
898 Finalmente, se añade el código para trazar las dos líneas. Se usan
899 dos llamadas a @code{make-line-stencil} para trazar las líneas, y los
900 sellos resultantes se combinan usando @code{ly:stencil-add}:
902 @lilypond[quote,verbatim,ragged-right]
903 #(define-markup-command (my-draw-line layout props dest)
905 #:properties ((thickness 1)
908 (let* ((th (* (ly:output-def-lookup layout 'line-thickness)
913 (x (cond ((= dx 0) w)
915 (else (/ w (sqrt (+ 1 (* (/ dx dy) (/ dx dy))))))))
916 (y (* (if (< (* dx dy) 0) 1 -1)
919 (else (/ w (sqrt (+ 1 (* (/ dy dx) (/ dy dx))))))))))
920 (ly:stencil-add (make-line-stencil th x y (+ dx x) (+ dy y))
921 (make-line-stencil th (- x) (- y) (- dx x) (- dy y)))))
923 \markup \my-draw-line #'(4 . 3)
924 \markup \override #'(line-gap . 1.2) \my-draw-line #'(4 . 3)
928 @node Definición de nuevas instrucciones de lista de marcado
929 @subsection Definición de nuevas instrucciones de lista de marcado
930 @translationof New markup list command definition
932 Las instrucciones de listas de marcado se definen con el macro de
933 Scheme @code{define-markup-list-command}, que es similar al macro
934 @code{define-markup-command} descrito en @ref{Definición de una
935 instrucción de marcado nueva}, excepto que donde éste devuelve un
936 sello único, aquél devuelve una lista de sellos.
938 En el siguiente ejemplo se define una instrucción de lista de marcado
939 @code{\paragraph}, que devuelve una lista de líneas justificadas,
940 estando la primera de ellas sangrada. La anchura del sangrado se toma
941 del argumento @code{props}.
944 #(define-markup-list-command (paragraph layout props args) (markup-list?)
945 #:properties ((par-indent 2))
946 (interpret-markup-list layout props
947 #@{\markuplines \justified-lines @{ \hspace #$par-indent $args @} #@}))
951 The version using just Scheme is more complex:
953 #(define-markup-list-command (paragraph layout props args) (markup-list?)
954 #:properties ((par-indent 2))
955 (interpret-markup-list layout props
956 (make-justified-lines-markup-list (cons (make-hspace-markup par-indent)
960 Aparte de los argumentos usuales @code{layout} y @code{props}, la
961 instrucción de lista de marcados @code{paragraph} toma un argumento de
962 lista de marcados, llamado @code{args}. El predicado para listas de
963 marcados es @code{markup-list?}.
965 En primer lugar, la función toma el ancho del sangrado, una propiedad
966 llamada aquí @code{par-indent}, de la lista de propiedades
967 @code{props}. Si no se encuentra la propiedad, el valor
968 predeterminado es @code{2}. Después, se hace una lista de líneas
969 justificadas usando la instrucción incorporada de lista de marcados
970 @code{\justified-lines}, que está relacionada con la función
971 @code{make-justified-lines-markup-list}. Se añade un espacio
972 horizontal al principio usando @code{\hspace} (o la función
973 @code{make-hspace-markup}). Finalmente, la lista de marcados se
974 interpreta usando la función @code{interpret-markup-list}.
976 Esta nueva instrucción de lista de marcados se puede usar como sigue:
981 El arte de la tipografía musical se llama \italic @{grabado (en plancha).@}
982 El término deriva del proceso tradicional de impresión de música.
983 hace sólo algunas décadas, las partituras se hacían cortando y estampando
984 la música en una plancha de zinc o lata en una imagen invertida.
986 \override-lines #'(par-indent . 4) \paragraph @{
987 La plancha se tenía que entintar, y las depresiones causadas por los cortes
988 y estampados retienen la tinta. Se formaba una imagen presionando el papel
989 contra la plancha. El estampado y cortado se hacía completamente
996 @node Contextos para programadores
997 @section Contextos para programadores
998 @translationof Contexts for programmers
1001 * Evaluación de contextos::
1002 * Ejecutar una función sobre todos los objetos de la presentación::
1005 @node Evaluación de contextos
1006 @subsection Evaluación de contextos
1007 @translationof Context evaluation
1009 @cindex código, llamadas durante la interpretación
1010 @funindex \applyContext
1012 Se pueden modificar los contextos durante la interpretación con código
1013 de Scheme. La sintaxis para esto es
1016 \applyContext @var{función}
1019 @code{@var{función}} debe ser una función de Scheme que toma un único
1020 argumento, que es el contexto al que aplicarla. El código siguiente
1021 imprime el número del compás actual sobre la salida estándar durante
1027 (format #t "\nSe nos ha llamado en el compás número ~a.\n"
1028 (ly:context-property x 'currentBarNumber)))
1032 @node Ejecutar una función sobre todos los objetos de la presentación
1033 @subsection Ejecutar una función sobre todos los objetos de la presentación
1034 @translationof Running a function on all layout objects
1036 @cindex código, llamar sobre objetos de presentación
1037 @funindex \applyOutput
1040 La manera más versátil de realizar el ajuste fino de un objeto es
1041 @code{\applyOutput}, que
1042 funciona insertando un evento dentro del contexto especificado
1043 (@rinternals{ApplyOutputEvent}). Su sintaxis es
1046 \applyOutput @var{contexto} @var{proc}
1050 donde @code{@var{proc}} es una función de Scheme que toma tres argumentos.
1052 Al interpretarse, la función @code{@var{proc}} se llama para cada objeto de
1053 presentación que se encuentra en el contexto @code{@var{contexto}}
1054 en el tiempo actual, con los siguientes argumentos:
1057 @item el propio objeto de presentación,
1058 @item el contexto en que se creó el objeto de presentación, y
1059 @item el contexto en que se procesa @code{\applyOutput}.
1063 Además, la causa del objeto de presentación, es decir el objeto o
1064 expresión musical que es responsable de haberlo creado, está en la
1065 propiedad @code{cause} del objeto. Por ejemplo, para la cabeza de una
1066 nota, éste es un evento @rinternals{NoteHead}, y para un objeto
1067 plica, éste es un objeto @rinternals{Stem}.
1069 He aquí una función que usar para @code{\applyOutput}; borra las
1070 cabezas de las notas que están sobre la línea central y junto a ella:
1072 @lilypond[quote,verbatim,ragged-right]
1073 #(define (blanker grob grob-origin context)
1074 (if (and (memq 'note-head-interface (ly:grob-interfaces grob))
1075 (< (abs (ly:grob-property grob 'staff-position)) 2))
1076 (set! (ly:grob-property grob 'transparent) #t)))
1079 a'4 e8 <<\applyOutput #'Voice #blanker a c d>> b2
1084 @node Funciones de callback
1085 @section Funciones de callback
1086 @translationof Callback functions
1088 Las propiedades (como @code{thickness} (grosor), @code{direction}
1089 (dirección), etc.) se pueden establecer a valores fijos con \override,
1093 \override Stem #'thickness = #2.0
1096 Las propiedades pueden fijarse también a un procedimiento de scheme,
1098 @lilypond[fragment,verbatim,quote,relative=2]
1099 \override Stem #'thickness = #(lambda (grob)
1100 (if (= UP (ly:grob-property grob 'direction))
1107 En este caso, el procedimiento se ejecuta tan pronto como el valor de
1108 la propiedad se reclama durante el proceso de formateo.
1110 Casi todo el motor de tipografiado está manejado por estos
1111 @emph{callbacks}. Entre las propiedades que usan normalmente
1112 @emph{callbacks} están
1116 La rutina de impresión, que construye un dibujo para el símbolo
1118 La rutina que establece la posición horizontal
1120 La rutina que calcula la anchura de un objeto
1123 El procedimiento siempre toma un argumento único, que es el grob (el
1126 Si se deben llamar rutinas con varios argumentos, el grob actual se
1127 puede insertar con una cerradura de grob. He aquí un ajuste
1128 procedente de @code{AccidentalSuggestion},
1132 ,(ly:make-simple-closure
1134 ,(ly:make-simple-closure
1135 (list ly:self-alignment-interface::centered-on-x-parent))
1136 ,(ly:make-simple-closure
1137 (list ly:self-alignment-interface::x-aligned-on-self)))))
1141 En este ejemplo, tanto
1142 @code{ly:self-alignment-interface::x-aligned-on-self} como
1143 @code{ly:self-alignment-interface::centered-on-x-parent} se llaman con
1144 el grob como argumento. El resultado se añade con la función
1145 @code{+}. Para asegurar que esta adición se ejecuta adecuadamente,
1146 todo ello se encierra dentro de @code{ly:make-simple-closure}.
1148 De hecho, usar un solo procedimiento como valor de una propiedad
1152 (ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
1156 El @code{ly:make-simple-closure} interior aporta el grob como
1157 argumento de @var{proc}, el exterior asegura que el resultado de la
1158 función es lo que se devuelve, en lugar del objeto
1159 @code{simple-closure}.
1161 Desde dentro de un callback, el método más fácil para evaluar un
1162 elemento de marcado es usar grob-interpret-markup. Por ejemplo:
1165 mi-callback = #(lambda (grob)
1166 (grob-interpret-markup grob (markup "fulanito")))
1170 @node Código de Scheme en línea
1171 @section Código de Scheme en línea
1172 @translationof Inline Scheme code
1174 La principal desventaja de @code{\tweak} es su inflexibilidad
1175 sintáctica. Por ejemplo, lo siguiente produce un error de sintaxis.
1178 F = \tweak #'font-size #-3 -\flageolet
1186 En otras palabras, @code{\tweak} no se comporta como una articulación
1187 en cuando a la sintaxis; concretamente, no se puede adjuntar con
1188 @code{^} y @code{_}.
1190 Usando Scheme, se puede dar un rodeo a este problema. La ruta hacia
1191 el resultado se da en @ref{Añadir articulaciones a las notas
1192 (ejemplo)}, especialmente cómo usar @code{\displayMusic} como guía de
1196 F = #(let ((m (make-music 'ArticulationEvent
1197 'articulation-type "flageolet")))
1198 (set! (ly:music-property m 'tweaks)
1199 (acons 'font-size -3
1200 (ly:music-property m 'tweaks)))
1209 Aquí, las propiedades @code{tweaks} del objeto flageolet @code{m}
1210 (creado con @code{make-music}) se extraen con
1211 @code{ly:music-property}, se antepone un nuevo par clave-valor para
1212 cambiar el tamaño de la tipografía a la lista de propiedades con la
1213 función de Scheme @code{acons}, y finalmente el resultado se escribe
1214 de nuevo con @code{set!}. El último elemento del bloque @code{let} es
1215 el valor de retorno, el propio @code{m}.
1218 @node Trucos difíciles
1219 @section Trucos difíciles
1220 @translationof Difficult tweaks
1222 Hay un cierto número de tipos de ajustes difíciles.
1228 Un tipo de ajuste difícil es la apariencia de los objetos de
1229 extensión, como las ligaduras de expresión y de unión. Inicialmente,
1230 sólo se crea uno de estos objetos, y pueden ajustarse con el mecanismo
1231 normal. Sin embargo, en ciertos casos los objetos extensores cruzan
1232 los saltos de línea. Si esto ocurre, estos objetos se clonan. Se
1233 crea un objeto distinto por cada sistema en que se encuentra. Éstos
1234 son clones del objeto original y heredan todas sus propiedades,
1235 incluidos los @code{\override}s.
1237 En otras palabras, un @code{\override} siempre afecta a todas las
1238 piezas de un objeto de extensión fragmentado. Para cambiar sólo una
1239 parte de un extensor en el salto de línea, es necesario inmiscuirse en
1240 el proceso de formateado. El @emph{callback}
1241 @code{after-line-breaking} contiene el procedimiento Scheme que se
1242 llama después de que se han determinado los saltos de línea, y los
1243 objetos de presentación han sido divididos sobre los distintos
1246 En el ejemplo siguiente, definimos un procedimiento
1247 @code{my-callback}. Este procedimiento
1251 determina si hemos sido divididos por los saltos de línea
1253 en caso afirmativo, reúne todos los objetos divididos
1255 comprueba si somos el último de los objetos divididos
1257 en caso afirmativo, establece @code{extra-offset}.
1260 Este procedimiento se instala en @rinternals{Tie} (ligadura de unión),
1261 de forma que la última parte de la ligadura dividida se traslada hacia
1264 @lilypond[quote,verbatim,ragged-right]
1265 #(define (my-callback grob)
1267 ;; have we been split?
1268 (orig (ly:grob-original grob))
1270 ;; if yes, get the split pieces (our siblings)
1271 (siblings (if (ly:grob? orig)
1272 (ly:spanner-broken-into orig)
1275 (if (and (>= (length siblings) 2)
1276 (eq? (car (last-pair siblings)) grob))
1277 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1280 \override Tie #'after-line-breaking =
1288 Al aplicar este truco, la nueva función de callback
1289 @code{after-line-breaking} también debe llamar a la antigua,
1290 si existe este valor predeterminado. Por ejemplo, si se usa con
1291 @code{Hairpin}, se debe llamar también a
1292 @code{ly:spanner::kill-zero-spanned-time}.
1295 @item Algunos objetos no se pueden cambiar con @code{\override} por
1296 razones técnicas. Son ejemplos @code{NonMusicalPaperColumn} y
1297 @code{PaperColumn}. Se pueden cambiar con la función
1298 @code{\overrideProperty} que funciona de forma similar a @code{\once
1299 \override}, pero usa una sintaxis distinta.
1303 #"Score.NonMusicalPaperColumn" % Nombre del grob
1304 #'line-break-system-details % Nombre de la propiedad
1305 #'((next-padding . 20)) % Valor
1308 Observe, sin embargo, que @code{\override}, aplicado a
1309 @code{NonMusicalPaperColumn} y a @code{PaperColumn}, aún funciona
1310 como se espera dentro de los bloques @code{\context}.
1315 @node Interfaces de Scheme de LilyPond
1316 @chapter Interfaces de Scheme de LilyPond
1317 @translationof LilyPond Scheme interfaces
1319 Este capítulo cubre las diversas herramientas proporcionadas por
1320 LilyPond como ayuda a los programadores de Scheme a extraer e
1321 introducir información de los flujos musicales.
1323 HACER @c TODO -- figure out what goes in here and how to organize it