@c -*- coding: utf-8; mode: texinfo; documentlanguage: es -*-
@c This file is part of lilypond.tely
@ignore
- Translation of GIT committish: 4a527608c5ff2ce31e596495d00dce181dc1b9ea
+ Translation of GIT committish: d4f58bb3ad4e7fe1967a6b48f25e3addffc8aa14
When revising a translation, copy the HEAD committish of the
version that you are working on. See TRANSLATION for details.
@end ignore
-@c \version "2.11.61"
+@c \version "2.12.0"
@node Interfaces for programmers
@chapter Interfaces for programmers
Se pueden realizar trucos avanzados mediante el uso de Scheme. Si no
-está familizarizado con Scheme, le conviene leer nuestro tutorial de
+está familiarizado con Scheme, le conviene leer nuestro tutorial de
Scheme, @rlearning{Scheme tutorial}.
@menu
LilyPond. La forma general de estas funciones es:
@example
-funcion =
-#(define-music-function (parser location @var{var1} @var{var2}... )
- (@var{var1-type?} @var{var2-type?}...)
+function =
+#(define-music-function (parser location @var{var1} @var{var2}...@var{vari}... )
+ (@var{var1-type?} @var{var2-type?}...@var{vari-type?}...)
#@{
@emph{...música...}
#@})
donde
@multitable @columnfractions .33 .66
-@item @var{argi} @tab @var{i}-ésima variable
-@item @var{argi-type?} @tab tipo de variable
-@item @var{...música...} @tab entrada normal de LilyPond, usando las variables como @code{#$var1}.
+@item @var{vari} @tab @var{i}-ésima variable
+@item @var{vari-type?} @tab tipo de la @var{i}-ésima variable
+@item @var{...música...} @tab entrada normal de LilyPond, usando las variables como @code{#$var1}, etc.
@end multitable
Los siguientes tipos de entrada se pueden usar como variables en una
variables.
@multitable @columnfractions .33 .66
-@headitem Tipo de entrada @tab notación de @var{argi-type?}
+@headitem Tipo de entrada @tab notación de @var{vari-type?}
@item Entero @tab @code{integer?}
@item Flotante (número decimal) @tab @code{number?}
@item Cadena de texto @tab @code{string?}
@item Pareja de variables @tab @code{pair?}
@end multitable
-Los argumentos @code{parser} y @code{location} son obligatorios, y
-se usan en ciertas situaciones avanzadas. El argumento
-@code{parser} se usa para acceder al valor de otra variable de
-LilyPond. El argumento @code{location} se usa para establecer el
-@q{origen} de la expresión musical que construye la función musical,
-de forma que en caso de producirse un error de sintaxis LilyPond pueda
-informar al usuario de un lugar adecuado donde buscar en el archivo de
-entrada.
+Los argumentos @code{parser} y @code{location} son obligatorios, y se
+usan en ciertas situaciones avanzadas. El argumento @code{parser} se
+usa para tener acceso al valor de otra variable de LilyPond. El
+argumento @code{location} se usa para establecer el @q{origen} de la
+expresión musical que construye la función musical, de forma que en
+caso de producirse un error de sintaxis LilyPond pueda informar al
+usuario de un lugar adecuado donde buscar en el archivo de entrada.
@node Simple substitution functions
{ c' d' e' f' \custosNote g' }
@end lilypond
-Se pueden usar más de una variable:
+Se puede usar más de una variable:
@lilypond[quote,verbatim,ragged-right]
-tempoMark = #(define-music-function (parser location padding marktext)
- (number? string?)
+tempoPadded = #(define-music-function (parser location padding tempotext)
+ (number? string?)
#{
- \once \override Score . RehearsalMark #'padding = $padding
- \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
- \mark \markup { \bold $marktext }
+ \once \override Score.MetronomeMark #'padding = $padding
+ \tempo \markup { \bold $tempotext }
#})
\relative c'' {
-c2 e
-\tempoMark #3.0 #"Allegro"
-g c
+ \tempo \markup { "Low tempo" }
+ c4 d e f g1
+ \tempoPadded #4.0 #"High tempo"
+ g4 f e d c1
}
@end lilypond
@node Void functions
@subsection Void functions
-Una función musical debe devolver una expresión musical, per a veces
+Una función musical debe devolver una expresión musical, pero a veces
podemos necesitar una función en la que no hay música en juego (como
la desactivación de la funcionalidad Apuntar y Pulsar). Para hacerlo,
devolvemos una expresión musical @code{void} (vacía).
#@{#@}))
@end example
-Para la imresión real de los números de compás donde se llama a esta
+Para la impresión real de los números de compás donde se llama a esta
función, invoque a @command{lilypond} con
@example
@end example
Esto supone que las variables de entrada y las variables de Scheme se
-pueden intermezclar con libertad. En el ejemplo siguiente, se
+pueden entremezclar con libertad. En el ejemplo siguiente, se
almacena un fragmento musical en la variable @code{traLaLa}, y se
-dupplica utilizando Scheme. El resultado se importa en un bloque
+duplica utilizando Scheme. El resultado se importa en un bloque
@code{\score} por medio de una segunda variable @code{twice}:
@lilypond[verbatim]
@code{ly:export}, un valor de Scheme se interpreta como si hubiera
sido introducido en sintaxis de LilyPond. En vez de definir
@code{\twice}, el ejemplo anterior podría también haberse escrito como
+
@example
-@dots{}
+...
@{ #(ly:export (make-sequential-music (list newLa))) @}
@end example
-El sódigo de Scheme se evalúa tan pronto como el analizador sintáctico
+El código de Scheme se evalúa tan pronto como el analizador sintáctico
lo encuentra. Para definir código de Scheme en un macro (para
llamarlo con posterioridad), use @ref{Void functions}, o bien
expressions}.
@item
-@q{typo} o intterface: cada nombre de música tiene varios @q{tipos} o
+@q{tipo} o interface: cada nombre de música tiene varios @q{tipos} o
interfaces, por ejemplo una nota es un @code{event}, pero también es
un @code{note-event}, un @code{rhythmic-event} y un
@code{melodic-event}. Todas las clases musicales se encuentran
@rinternals{Music properties}.
Una expresión musical compuesta es un objeto musical que contiene
-otros objetos musicales en sus propiedades. Se puede almacernar una
+otros objetos musicales en sus propiedades. Se puede almacenar una
lista de objetos en la propiedad @code{elements} de un objeto musical,
o un solo objeto musical @q{hijo} en la propiedad @code{element}. Por
ejemplo, @rinternals{SequentialMusic} tiene sus hijos en
@subsection Displaying music expressions
@cindex interno, almacenamiento
+@cindex mostrar expresiones musicales
+@cindex interna, representación, mostrar
+
@funindex \displayMusic
Si se está escribiendo una función musical puede ser muy instructivo
lilypond archivo.ly >resultado.txt
@end example
-Con la aplicación de un poco de formato, la inforamción anterior es
+Con la aplicación de un poco de formato, la información anterior es
fácil de leer:
@example
como una expresión @code{EventChord} que contiene un objeto
@code{NoteEvent} (que almacena las propiedades de duración y altura) y
cualquier otra información adicional (en este caso, un evento
-@code{AbsoluteDynamicEvent} con una porpiedad de texto @code{"f"}.
+@code{AbsoluteDynamicEvent} con una propiedad de texto @code{"f"}.
@node Music properties
1)))))
@end example
-Las malas noticias son que las espresiones @code{SlurEvent} se deben
+Las malas noticias son que las expresiones @code{SlurEvent} se deben
añadir @q{dentro} de la nota (o más concretamente, dentro de la
expresión @code{EventChord}).
@example
(define (add-marcato event-chord)
"Añadir una ArticulationEvent de marcato a los elementos de `event-chord',
- que se ssupone que es una expresión EventChord."
+ que se supone que es una expresión EventChord."
(let ((result-event-chord (ly:music-deep-copy event-chord)))
(set! (ly:music-property result-event-chord 'elements)
(cons (make-music 'ArticulationEvent
el marcato a su propiedad lista de elementos.
@example
-(set! place new-value)
+(set! lugar valor-nuevo)
@end example
-Aquí, lo que queremos establecer (el @q{place}) es la propiedad
+Aquí, lo que queremos establecer (el @q{lugar}) es la propiedad
@q{elements} de la expresión @code{result-event-chord}.
@example
(ly:music-property result-event-chord 'elements))
@end example
-@code{cons} se usa para añadir un elemento a una lsita sin modificar
+@code{cons} se usa para añadir un elemento a una lista sin modificar
la lista original. Esto es lo que queremos: la misma lista que antes,
más la nueva expresión @code{ArticulationEvent}. El orden dentro de
la propiedad elements no es importante aquí.
@example
addMarcato = #(define-music-function (parser location event-chord)
(ly:music?)
- "Add a marcato ArticulationEvent to the elements of `event-chord',
- which is supposed to be an EventChord expression."
+ "Añadir un ArticulationEvent de marcato a los elementos de `event-chord',
+ que se supone que es una expresión EventChord."
(let ((result-event-chord (ly:music-deep-copy event-chord)))
(set! (ly:music-property result-event-chord 'elements)
(cons (make-music 'ArticulationEvent
@noindent
Este ejemplo muestra las principales reglas de traducción entre la
-sitaxis del marcado normal de LilyPond y la sintaxis del marcado de
+sintaxis del marcado normal de LilyPond y la sintaxis del marcado de
Scheme.
@quotation
@example
#(define-markup-list-command (paragraph layout props args) (markup-list?)
(let ((indent (chain-assoc-get 'par-indent props 2)))
- (interpret-markup-list layout props
+ (interpret-markup-list layout props
(make-justified-lines-markup-list (cons (make-hspace-markup indent)
args)))))
@end example
lista de marcados, llamado @code{args}. El predicado para listas de
marcados es @code{markup-list?}.
-Em primer lugar, la función toma el ancho del sangrado, una propiedad
+En primer lugar, la función toma el ancho del sangrado, una propiedad
llamada aquí @code{par-indent}, de la lista de propiedades
@code{props}. Si no se encuentra la propiedad, el valor
predeterminado es @code{2}. Después, se hace una lista de líneas
@node Running a function on all layout objects
@subsection Running a function on all layout objects
-@untranslated
+
+@cindex código, llamar sobre objetos de presentación
+@funindex \applyOutput
+
+
+La manera más versátil de realizar el ajuste fino de un objeto es
+@code{\applyOutput}. Su sintaxis es
+
+@example
+\applyOutput @var{contexto} @var{proc}
+@end example
+
+@noindent
+donde @var{proc} es una función de Scheme, que toma tres argumentos.
+
+Al interpretarse, la función @var{proc} se llama para cada objeto de
+presentación que se encuentra en el contexto @var{contexto}, con los
+siguientes argumentos:
+
+@itemize
+@item el propio objeto de presentación,
+@item el contexto en que se creó el objeto de presentación, y
+@item el contexto en que se procesa @code{\applyOutput}.
+@end itemize
+
+Además, la causa del objeto de presentación, es decir el objeto o
+expresión musical que es responsable de haberlo creado, está en la
+propiedad @code{cause} del objeto. Por ejemplo, para la cabeza de una
+nota, éste es un evento @rinternals{NoteHead}, y para un objeto
+@rinternals{Stem} (plica), éste es un objeto @rinternals{Stem}.
+@c Impossible - changed to Stem --FV
+
+He aquí una función que usar para @code{\applyOutput}; borra las
+cabezas de las notas que están sobre la línea central:
+
+@lilypond[quote,verbatim,ragged-right]
+#(define (blanker grob grob-origin context)
+ (if (and (memq 'note-head-interface (ly:grob-interfaces grob))
+ (eq? (ly:grob-property grob 'staff-position) 0))
+ (set! (ly:grob-property grob 'transparent) #t)))
+
+\relative {
+ e4 g8 \applyOutput #'Voice #blanker b d2
+}
+@end lilypond
@node Scheme procedures as properties
@section Scheme procedures as properties
-@untranslated
+Las propiedades (como el grosor, la dirección, etc.) se pueden
+establecer a valores fijos con \override, p. ej.
+
+@example
+\override Stem #'thickness = #2.0
+@end example
+
+Las propiedades pueden fijarse también a un procedimiento de scheme,
+
+@lilypond[fragment,verbatim,quote,relative=2]
+\override Stem #'thickness = #(lambda (grob)
+ (if (= UP (ly:grob-property grob 'direction))
+ 2.0
+ 7.0))
+c b a g b a g b
+@end lilypond
+
+@noindent
+En este caso, el procedimiento se ejecuta tan pronto como el valor de
+la propiedad se reclama durante el proceso de formateo.
+
+Casi todo el motor de tipografiado está manejado por estos
+@emph{callbacks}. Entre las propiedades que usan normalmente
+@emph{callbacks} están
+
+@table @code
+@item stencil
+ La rutina de impresión, que construye un dibujo para el símbolo
+@item X-offset
+ La rutina que establece la posición horizontal
+@item X-extent
+ La rutina que calcula la anchura de un objeto
+@end table
+
+El procedimiento siempre toma un argumento único, que es el grob (el
+objeto gráfico).
+Si se deben llamar rutinas con varios argumentos, el grob actual se
+puede insertar con una cerradura de grob. He aquí un ajuste
+procedente de @code{AccidentalSuggestion},
+
+@example
+(X-offset .
+ ,(ly:make-simple-closure
+ `(,+
+ ,(ly:make-simple-closure
+ (list ly:self-alignment-interface::centered-on-x-parent))
+ ,(ly:make-simple-closure
+ (list ly:self-alignment-interface::x-aligned-on-self)))))
+@end example
+
+@noindent
+En este ejemplo, tanto
+@code{ly:self-alignment-interface::x-aligned-on-self} como
+@code{ly:self-alignment-interface::centered-on-x-parent} se llaman con
+el grob como argumento. El resultado se añade con la función
+@code{+}. Para asegurar que esta adición se ejecuta adecuadamente,
+todo ello se encierra dentro de @code{ly:make-simple-closure}.
+
+De hecho, usar un solo procedimiento como valor de una propiedad
+equivale a
+
+@example
+(ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
+@end example
+
+@noindent
+El @code{ly:make-simple-closure} interior aporta el grob como
+argumento de @var{proc}, el exterior asegura que el resultado de la
+función es lo que se devuelve, en lugar del objeto
+@code{simple-closure}.
@node Using Scheme code instead of \tweak
@section Using Scheme code instead of @code{\tweak}
-@untranslated
+La principal desventaja de @code{\tweak} es su inflexibilidad
+sintáctica. Por ejemplo, lo siguiente produce un error de sintaxis.
+@example
+F = \tweak #'font-size #-3 -\flageolet
+
+\relative c'' @{
+ c4^\F c4_\F
+@}
+@end example
+
+@noindent
+En otras palabras, @code{\tweak} no se comporta como una articulación
+en cuando a la sintaxis; concretamente, no se puede adjuntar con
+@code{^} y @code{_}.
+
+Usando Scheme, se puede dar un rodeo a este problema. La ruta hacia
+el resultado se da en @ref{Adding articulation to notes (example)},
+especialmente cómo usar @code{\displayMusic} como guía de ayuda.
+
+@example
+F = #(let ((m (make-music 'ArticulationEvent
+ 'articulation-type "flageolet")))
+ (set! (ly:music-property m 'tweaks)
+ (acons 'font-size -3
+ (ly:music-property m 'tweaks)))
+ m)
+
+\relative c'' @{
+ c4^\F c4_\F
+@}
+@end example
+
+@noindent
+Aquí, las propiedades @code{tweaks} del objeto flageolet @code{m}
+(creado con @code{make-music}) se extraen con
+@code{ly:music-property}, se antepone un nuevo par clave-valor para
+cambiar el tamaño de la tipografía a la lista de propiedades con la
+función de Scheme @code{acons}, y finalmente el resultado se escribe
+de nuevo con @code{set!}. El último elemento del bloque @code{let} es
+el valor de retorno, el propio @code{m}.
@node Difficult tweaks
@section Difficult tweaks
-@untranslated
+Hay un cierto número de tipos de ajustes difíciles.
+
+@itemize
+
+@item
+Un tipo de ajuste difícil es la apariencia de los objetos de
+extensión, como las ligaduras de expresión y de unión. Inicialmente,
+sólo se crea uno de estos objetos, y pueden ajustarse con el mecanismo
+normal. Sin embargo, en ciertos casos los objetos extensores cruzan
+los saltos de línea. Si esto ocurre, estos objetos se clonan. Se
+crea un objeto distinto por cada sistema en que se encuentra. Éstos
+son clones del objeto original y heredan todas sus propiedades,
+incluidos los @code{\override}s.
+
+En otras palabras, un @code{\override} siempre afecta a todas las
+piezas de un objeto de extensión fragmentado. Para cambiar sólo una
+parte de un extensor en el salto de línea, es necesario inmiscuirse en
+el proceso de formateado. El @emph{callback}
+@code{after-line-breaking} contiene el procedimiento Scheme que se
+llama después de que se han determinado los saltos de línea, y los
+objetos de presentación han sido divididos sobre los distintos
+sistemas.
+
+En el ejemplo siguiente, definimos un procedimiento
+@code{my-callback}. Este procedimiento
+
+@itemize
+@item
+determina si hemos sido divididos por los saltos de línea
+@item
+en caso afirmativo, reúne todos los objetos divididos
+@item
+comprueba si somos el último de los objetos divididos
+@item
+en caso afirmativo, establece @code{extra-offset}.
+@end itemize
+
+Este procedimiento se instala en @rinternals{Tie} (ligadura de unión),
+de forma que la última parte de la ligadura dividida se traslada hacia
+arriba.
+
+@lilypond[quote,verbatim,ragged-right]
+#(define (my-callback grob)
+ (let* (
+ ; have we been split?
+ (orig (ly:grob-original grob))
+
+ ; if yes, get the split pieces (our siblings)
+ (siblings (if (ly:grob? orig)
+ (ly:spanner-broken-into orig) '() )))
+
+ (if (and (>= (length siblings) 2)
+ (eq? (car (last-pair siblings)) grob))
+ (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
+
+\relative c'' {
+ \override Tie #'after-line-breaking =
+ #my-callback
+ c1 ~ \break c2 ~ c
+}
+@end lilypond
+
+@noindent
+Al aplicar este truco, la nueva función de callback
+@code{after-line-breaking} también debe llamar a la antigua
+@code{after-line-breaking}, si existe. Por ejemplo, si se usa con
+@code{Hairpin}, se debe llamar también a
+@code{ly:hairpin::after-line-breaking}.
+
+
+@item Algunos objetos no se pueden cambiar con @code{\override} por
+razones técnicas. Son ejemplos @code{NonMusicalPaperColumn} y
+@code{PaperColumn}. Se pueden cambiar con la función
+@code{\overrideProperty} que funciona de forma similar a @code{\once
+\override}, pero usa una sintaxis distinta.
+
+@example
+\overrideProperty
+#"Score.NonMusicalPaperColumn" % Nombre del grob
+#'line-break-system-details % Nombre de la propiedad
+#'((next-padding . 20)) % Valor
+@end example
+
+Observe, sin embargo, que @code{\override}, aplicado a
+@code{NonMusicalPaperColumn} y a @code{PaperColumn}, aún funciona
+como se espera dentro de los bloques @code{\context}.
+
+@end itemize
projects / lilypond.git / blobdiff