Doc-es: full update, part I.

[lilypond.git] / Documentation / es / notation / changing-defaults.itely

@c -*- coding: utf-8; mode: texinfo; documentlanguage: es -*-

@ignore
Translation of GIT committish: e90fa9a8a1d71251a2c047e69798be05938a1241

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  For details, see the Contributors'
    Guide, node Updating translation committishes..
@end ignore

@c \version "2.12.0"

@node Cambiar los valores por omisión
@chapter Cambiar los valores por omisión
@translationof Changing defaults

El objetivo del diseño de LilyPond es proporcionar la más alta calidad
de los resultados, de forma predeterminada.  A pesar de ello, podría
tener que cambiar este resultado predeterminado.  La disposición sobre
el papel se controla a través de un amplio número de @q{botones e
interruptores} llamados en su conjunto @q{propiedades}.  En el Manual
de aprendizaje podemos encontrar una introducción en forma de tutorial
al acceso y modificación de estas propiedades, véase
@rlearning{Trucar la salida}.  Éste debería leerse en primer lugar.
Este capítulo cubre un terreno similar, pero con un estilo más
adecuado para un manual de referencia.

@cindex Referencia de funcionamiento interno

La descripción definitiva de los controles que están disponibles para
su ajuste fino están en un documento aparte: la
@rinternalsnamed{Top,Referencia de funcionamiento interno}.
Dicho manual relaciona todas
las variables, funciones y opciones que se encuentran disponibles en
LilyPond.  Está escrito como un documento HTML, que se puede encontrar
@c leave the @uref as one long line.
@uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/user/@/lilypond@/-internals/,en línea},
pero que también va incluido en el paquete de la documentación de LilyPond.

Internamente, LilyPond utiliza el lenguaje Scheme (un dialecto de
LISP) para aportar la infraestructura.  La sobreescritura de las
decisiones de disposición da acceso efectivo a las interioridades del
programa, lo que requiere código de Scheme como entrada.  Los
elementos de Scheme se inauguran dentro de un archivo @code{.ly} con
el símbolo de cuadradillo @code{#}.@footnote{@rextend{Tutorial de
Scheme} contiene un breve tutorial sobre la introducción de números,
listas, cadenas y símbolos en Scheme.}

@menu
* Contextos de interpretación::
* Explicación del Manual de referencia de funcionamiento interno::
* Modificar las propiedades::
* Conceptos y propiedades útiles::
* Trucos avanzados::
* Uso de las funciones musicales::
@end menu


@node Contextos de interpretación
@section Contextos de interpretación
@translationof Interpretation contexts

Esta sección explica qué son los contextos y cómo modificarlos.

@menu
* Explicación de los contextos::
* Crear contextos::
* Mantener vivos los contextos::
* Modificar los complementos (plug-ins) de contexto::
* Cambiar los valores por omisión de los contextos::
* Definir contextos nuevos::
* Alinear los contextos::
@end menu


@seealso
Manual de aprendizaje:
@rlearning{Contextos y grabadores}.

Archivos de inicio:
@file{ly/@/engraver@/-init@/.ly},
@file{ly/@/performer@/-init@/.ly}.

Fragmentos de código:
@rlsr{Contexts and engravers}.

Referencia de funcionamiento interno:
@rinternals{Contexts},
@rinternals{Engravers and Performers}.


@node Explicación de los contextos
@subsection Explicación de los contextos
@translationof Contexts explained

Los contextos se disponen de forma jerárquica:

@menu
* Score. El contexto maestro::
* Contextos del nivel superior.  Contenedores de pentagramas::
* Contextos de nivel intermedio. Pentagramas::
* Contextos del nivel más bajo. Voces::
@end menu

@node Score. El contexto maestro
@unnumberedsubsubsec Score. El contexto maestro
@translationof Score - the master of all contexts

Este es el contexto de notación del nivel más alto.  Ningún otro
contexto puede contener a un contexto Score.  De forma predeterminada,
el contexto Score maneja la administración de las indicaciones de
compás y se asegura de que ciertos elementos como claves, compases y
armaduras están siempre alineados entre los distintos pentagramas.

Se crea implícitamente una instancia del contexto Score cuando se
procesa un bloque @code{\score @{@dots{}@}} o @code{\layout
@{@dots{}@}}, o explícitamente cuando se ejecuta una instrucción
@code{\new Score}.

@node Contextos del nivel superior. Contenedores de pentagramas
@unnumberedsubsubsec Contextos del nivel superior: contenedores de pentagramas
@translationof Top-level contexts - staff containers

@strong{@emph{StaffGroup}}

Agrupa pentagramas y añade un corchete en la parte izquierda, formando
un grupo.  Las líneas divisorias de los pentagramas contenidos se
conectan verticalmente.  @code{StaffGroup} sólo consiste en una
colección de pentagramas, con un corchete delante y líneas divisorias
de arriba a abajo.

@strong{@emph{ChoirStaff}}

Idéntico a @code{StaffGroup} excepto que las barras de compás de los
pentagramas contenidos no se conectan verticalmente.

@strong{@emph{GrandStaff}}

Un grupo de pentagramas, con una llave en la parte izquierda que
abarca el grupo.  Las barras de compás de los pentagramas contenidos
se conectan verticalmente.

@strong{@emph{PianoStaff}}

Igual que @code{GrandStaff}, pero contempla la posibilidad de poner el
nombre del instrumento a la izquierda del sistema.

@node Contextos de nivel intermedio. Pentagramas
@unnumberedsubsubsec Contextos de nivel intermedio. Pentagramas
@translationof Intermediate-level contexts - staves

@strong{@emph{Staff}}

Maneja claves, barras de compás, tonalidades y alteraciones
accidentales.  Puede contener contextos de @code{Voice}.

@strong{@emph{RhythmicStaff}}

Como @code{Staff}, pero para imprimir ritmos.  Se ignoran las alturas
de las notas; las notas se imprimen sobre una línea.

@strong{@emph{TabStaff}}

Contexto para generar tablaturas.  De forma predeterminada dispone la
expresión musical como una tablatura de guitarra, impresa sobre seis
líneas.

@strong{@emph{DrumStaff}}

Maneja el tipografiado para instrumentos de percusión.  Puede contener
contextos @code{DrumVoice}.

@strong{@emph{VaticanaStaff}}

Igual que @code{Staff}, excepto que está pensado para tipografiar
piezas en estilo gregoriano.

@strong{@emph{MensuralStaff}}

Igual que @code{Staff}, excepto que está diseñado para tipografiar
piezas en estilo mensural.


@node Contextos del nivel más bajo. Voces
@unnumberedsubsubsec Contextos del nivel más bajo. Voces
@translationof Bottom-level contexts - voices

Los contextos del mismo nivel que Voice dan un valor inicial a ciertas
propiedades e inician los grabadores correspondientes.  Siendo
contextos del nivel más bajo, no pueden contener a otros contextos.

@strong{@emph{Voice}}

Corresponde a una voz sobre un pentagrama. este contexto maneja la
conversión de las indicaciones dinámicas, plicas, barras, subíndices y
superíndices, ligaduras de expresión y de unión, y silencios.  Tenemos
que crear instancias explícitas de este contexto si necesitamos varias
voces en el mismo pentagrama.

@strong{@emph{VaticanaVoice}}

Lo mismo que @code{Voice}, excepto que está diseñado para tipografiar
piezas en estilo gregoriano.

@strong{@emph{MensuralVoice}}

Lo mismo que @code{Voice}, con modificaciones para el tipografiado de
piezas en estilo mensural.

@strong{@emph{Lyrics}}

Corresponde a una voz con letra.  Maneja la impresión de una sola
línea de letra.

@strong{@emph{DrumVoice}}

El contexto de voz utilizado en una pauta de percusión.

@strong{@emph{FiguredBass}}

El contexto en que los objetos @code{BassFigure} se crean a partir de
la entrada escrita en el modo @code{\figuremode}.

@strong{@emph{TabVoice}}

El contexto de voz utilizado dentro de un contexto @code{TabStaff}.
Se suele dejar que se cree implícitamente.

@strong{@emph{CueVoice}}

El contexto de voz que se utiliza para dibujar notas de tamaño
reducido, con el principal objetivo de añadir notas guía de un
pentagrama a otro, véase @ref{Formateo de las notas guía}.
Normalmente se deja que se cree implícitamente.

@strong{@emph{ChordNames}}

Tipografía nombres de acordes.


@node Crear contextos
@subsection Crear contextos
@translationof Creating contexts

Para partituras que sólo tienen una voz y un pentagrama, los contextos
se crean automáticamente.  Para partituras más complejas, es necesario
crearlos a mano.  Existen tres instrucciones que hacen esto.

@itemize

@item
La instrucción más fácil es @code{\new}, y es también la más rápida de
escribir.  Se antepone a una expresión musical, por ejemplo

@funindex \new
@cindex nuevos, contextos
@cindex Contexto, creación de

@example
\new @var{tipo} @var{expresión_musical}
@end example

@noindent
donde @var{tipo} es el nombre de un contexto (como @code{Staff} o
@code{Voice}).  Esta instrucción crea un contexto nuevo, y empieza a
interpretar la @var{expresión_musical} con él.

Una aplicación práctica de @code{\new} es una partitura con muchos
pentagramas.  Cada parte que debe ir en su propio pentagrama, va
precedida de @code{\new Staff}.

@lilypond[quote,verbatim,relative=2,ragged-right,fragment]
<<
  \new Staff { c4 c }
  \new Staff { d4 d }
>>
@end lilypond

La instrucción @code{\new} puede también dar nombre al contexto,

@example
\new @var{tipo} = @var{identificador} @var{música}
@end example
Sin embargo, este nombre especificado por el usuario sólo se utiliza
si no hay ya otro contexto anterior con el mismo nombre.


@funindex \context

@item
Como @code{\new}, la instrucción @code{\context} también dirige una
expresión musical a un objeto de contexto, pero da al contexto un
nombre explícito.  La sintaxis es

@example
\context @var{tipo} = @var{identificador} @var{música}
@end example

En esta forma, la instrucción buscará un contexto existente del
@var{tipo} especificado que tenga el nombre @var{identificador}.  Si
ese contexto aún no existe, se crea un contexto nuevo con el nombre
especificado.  Esto es útil si nos vamos a referir más tarde al
contexto.  Por ejemplo, cuando se escribe la letra, la melodía está
dentro de un contexto con nombre

@example
\context Voice = "@b{tenor}" @var{música}
@end example

@noindent
de forma que los textos se puedan alinear correctamente con sus notas,

@example
\new Lyrics \lyricsto "@b{tenor}" @var{letra}
@end example

@noindent

Otro uso posible de los contextos con nombre es la fusión de dos
expresiones musicales distintas en un solo contexto.  En el siguiente
ejemplo, se introducen por separado las articulaciones y las notas:

@example
musica = @{ c4 c4 @}
decoracion = @{ s4-. s4-> @}
@end example

se combinan enviando los dos al mismo contexto @code{Voice},

@example
<<
  \new Staff \context Voice = "A" \musica
  \context Voice = "A" \decoracion
>>
@end example
@lilypond[quote,ragged-right]
music = { c4 c4 }
arts = { s4-. s4-> }
\relative c'' <<
  \new Staff \context Voice = "A" \music
  \context Voice = "A" \arts
>>
@end lilypond

Con este mecanismo, es posible definir un @qq{urtext} (una edición
original), con la posibilidad de poner articulaciones distintas sobre
las mismas notas.

@cindex crear contextos

@item
La tercera instrucción para crear contextos es
@example
\context @var{tipo} @var{música}
@end example


@noindent
Esto es similar a @code{\context} con @code{= @var{identificador}},
pero se corresponde con cualquier contexto del tipo @var{tipo}, sin
importar qué nombre se le ha dado.

Esta variante se usa con expresiones musicales que se pueden
interpretar en varios niveles.  Por ejemplo, la instrucción
@code{\applyOutput} (véase @rextend{Ejecutar una función sobre todos
los objetos de la presentación}).  Sin una instrucción @code{\context}
explícita, normalmente se aplicaría a @code{Voice}

@example
\applyOutput #'@var{contexto} #@var{función}   % aplicar al contexto Voice
@end example

Para que se interprete dentro de los niveles de @code{Score} o
@code{Staff}, utilice las siguientes formas:

@example
\applyOutput #'Score #@var{función}
\applyOutput #'Staff #@var{función}
@end example

@end itemize

@node Mantener vivos los contextos
@subsection Mantener vivos los contextos
@translationof Keeping contexts alive

@cindex contextos, mantener vivos
@cindex contextos, tiempo de vida

Normalmente los contextos finalizan en el primer momento musical en
que no tienen nada que hacer.  Así, los contextos de @code{Voice}
mueren tan pronto como ya no contienen ningún evento; los contextos de
@code{Staff} mueren tan pronto como todos los contextos de
@code{Voice} que contenían ya no contengan ningún evento; etc.  Esto
puede ocasionar dificultades si se tiene que hacer referencia a
contextos anteriores que ya han muerto, por ejemplo, al cambiar de
pentagramas con instrucciones @code{\change}, asociar letra con una
voz mediante instrucciones @code{\lyricsto}, o cuando se añaden
eventos musicales adicionales a un contexto anterior.

Existe una excepción a esta regla general: precisamente uno de los
contextos de @code{Voice} que están dentro de un contexto de
@code{Staff} o de una construcción @code{<<...>>} persiste siempre
hasta el final de, contexto de @code{Staff} circundante o la
construcción @code{<<...>>}, incluso aunque puede haber períodos en
que no tiene nada que hacer.  El contexto que persiste de esta forma
será el primero que se encuentre en la primera construcción encerrada
entre llaves @code{@{...@}}, ignorando cualquiera que se encuentre
dentro de construcciones encerradas por ángulos dobles @code{<<...>>}.

Cualquier contexto se puede mantener vivo si nos aseguramos de que
tiene algo que hacer en cualquier momento musical dado.  Los
contextos de @code{Staff} se mantienen con vida si nos aseguramos de
que una de sus voces se mantiene viva.  Una manera de hacerlo es
añadir silencios de separación a una voz en paralelo con la música
real.  Éstos deben añadirse a todos y cada uno de los contextos de
@code{Voice} que se hayan de mantener vivos.  Si se van a usar
esporádicamente varias voces, es más seguro mantenerlas todas vivas en
lugar de tratar de confiar en las excepciones que hemos mencionado
arriba.

En el ejemplo siguiente, tanto la voz A como la voz B se mantienen
vivas de esta manera durante la duración de la pieza:

@lilypond[quote,verbatim]
musicA = \relative c'' { d4 d d d }
musicB = \relative c'' { g4 g g g }
keepVoicesAlive = {
  <<
    \new Voice = "A" { s1*5 }  % Keep Voice "A" alive for 5 bars
    \new Voice = "B" { s1*5 }  % Keep Voice "B" alive for 5 bars
  >>
}

music = {
  \context Voice = "A" {
    \voiceOneStyle
    \musicA
  }
  \context Voice = "B" {
    \voiceTwoStyle
    \musicB
  }
  \context Voice = "A" { \musicA }
  \context Voice = "B" { \musicB }
  \context Voice = "A" { \musicA }
}

\score {
  \new Staff <<
    \keepVoicesAlive
    \music
  >>
}
@end lilypond

@cindex letra, alineación con melodía esporádica

El ejemplo siguiente muestra cómo se puede escribir una línea melódica
esporádica con letra utilizando este enfoque.  Por supuesto, en una
situación real la melodía y el acompañamiento consistirían en varias
secciones diferentes.

@lilypond[quote,verbatim]
melody = \relative c'' { a4 a a a }
accompaniment = \relative c' { d4 d d d }
words = \lyricmode { These words fol -- low the mel -- o -- dy }
\score {
  <<
    \new Staff = "music" {
      <<
        \new Voice = "melody" {
          \voiceOne
          s1*4  % Keep Voice "melody" alive for 4 bars
        }
        {
          \new Voice = "accompaniment" {
            \voiceTwo
            \accompaniment
          }
          <<
            \context Voice = "melody" { \melody }
            \context Voice = "accompaniment" { \accompaniment }
          >>
          \context Voice = "accompaniment" { \accompaniment }
          <<
            \context Voice = "melody" { \melody }
            \context Voice = "accompaniment" { \accompaniment }
          >>
        }
      >>
    }
    \new Lyrics \with { alignAboveContext = #"music" }
    \lyricsto "melody" { \words }
  >>
}
@end lilypond

Una forma alternativa, que podría resultar mejor en muchas
situaciones, es mantener con vida la línea melódica simplemente
incluyendo notas espaciadoras para alinearla correctamente con el
acompañamiento:

@lilypond[quote,verbatim]
melody = \relative c'' {
  s1  % skip a bar
  a4 a a a
  s1  % skip a bar
  a4 a a a
}
accompaniment = \relative c' {
  d4 d d d
  d4 d d d
  d4 d d d
  d4 d d d
}
words = \lyricmode { These words fol -- low the mel -- o -- dy }

\score {
  <<
    \new Staff = "music" {
      <<
        \new Voice = "melody" {
          \voiceOne
          \melody
        }
        \new Voice = "accompaniment" {
          \voiceTwo
          \accompaniment
        }
      >>
    }
    \new Lyrics \with { alignAboveContext = #"music" }
    \lyricsto "melody" { \words }
  >>
}
@end lilypond


@node Modificar los complementos (plug-ins) de contexto
@subsection Modificar los complementos (plug-ins) de contexto
@translationof Modifying context plug-ins

@c TODO Should this be Modifying engravers or Modifying contexts?

Los contextos de notación (como @code{Score} y @code{Staff}) no sólo
almacenan propiedades, también contienen «plug-ins» o complementos
llamados @q{grabadores} que crean elementos de notación.  Por ejemplo,
el contexto @code{Voice} contiene un grabador
@code{Note_head_engraver} que crea las cabezas de nota y el contexto
@code{Staff} contiene un grabador @code{Key_signature_engraver} que
crea la indicación de compás.

Para ver una descripción completa de todos y cada uno de los
complementos, consulte
@ifhtml
@rinternals{Engravers and Performers}.
@end ifhtml
@ifnothtml
Referencia de funcionamiento interno @expansion{} Traducción @expansion{} Grabadores.
@end ifnothtml
Cada contexto que se describe en
@ifhtml
@rinternals{Contexts}
@end ifhtml
@ifnothtml
Referencia de funcionamiento interno @expansion{} Traducción @expansion{} Contexto.
@end ifnothtml
relaciona los grabadores que se usan para ese contexto.


Puede ser de utilidad jugar un poco con estos complementos.  Se hace
iniciando un contexto nuevo con @code{\new} o @code{\context} y
modificándolo:

@funindex \with

@example
\new @var{contexto} \with @{
  \consists @dots{}
  \consists @dots{}
  \remove @dots{}
  \remove @dots{}
  @emph{etc.}
@}
@{
  @emph{..música..}
@}
@end example

@noindent
donde los @dots{} deben ser el nombre de un grabador.  Aquí tenemos un
ejemplo sencillo que suprime los grabadores
@code{Time_signature_engraver} y @code{Clef_engraver} de un contexto
@code{Staff}:

@lilypond[quote,relative=1,verbatim,fragment]
<<
  \new Staff {
    f2 g
  }
  \new Staff \with {
     \remove "Time_signature_engraver"
     \remove "Clef_engraver"
  } {
    f2 g2
  }
>>
@end lilypond

En el segundo pentagrama no hay indicación de compás ni clave.  Éste
es un método bastante rudimentario de hacer que desaparezcan los
objetos porque afecta a todo el pentagrama.  Este método también
afecta al espaciado, lo que puede ser deseable o no serlo.  Se
muestran métodos más sofisticados para quitar objetos en
@rlearning{Visibilidad y color de los objetos}.

El ejemplo siguiente muestra una aplicación práctica.  Normalmente las
líneas divisorias y las indicaciones de compás están sincronizadas a
lo largo de toda la partitura.  Lo hacen los grabadores
@code{Timing_translator} y @code{Default_bar_line_engraver}.  Estos
complementos mantienen al día la administración de las indicaciones de
compás, posición dentro del compás, etc.  Moviendo estos grabadores
desde el contexto de @code{Score} al de @code{Staff}, podemos
conseguir una partitura en la que cada pentagrama tiene su propio
compás independiente.

@cindex polimétricas, partituras
@cindex compases distintos al mismo tiempo

@lilypond[quote,relative=1,ragged-right,verbatim,fragment]
\new Score \with {
  \remove "Timing_translator"
  \remove "Default_bar_line_engraver"
} <<
  \new Staff \with {
    \consists "Timing_translator"
    \consists "Default_bar_line_engraver"
  } {
      \time 3/4
      c4 c c c c c
  }
  \new Staff \with {
    \consists "Timing_translator"
    \consists "Default_bar_line_engraver"
  } {
       \time 2/4
       c4 c c c c c
  }
>>
@end lilypond

@knownissues

Normalmente, el orden en que se especifican los grabadores no tiene
importancia, pero en algunos casos especiales sí la tiene, por ejemplo
donde un grabador escribe una propiedad y otro la lee, o donde un
grabador crea un groby otro debe procesarlo.  El orden en que los
grabadores se especifican es el orden en que se llaman para realizar
su tarea de procesamiento.

Las siguientes ordenaciones son importantes: el grabador de compases
@code{Bar_engraver} debe ir normalmente en primer lugar, y el grabador
de digitaciones @code{New_fingering_engraver} debe ir antes del
grabador @code{Script_column_engraver} de columnas de inscripciones.
Podría haber otros que tengan dependencias de ordenación.

@node Cambiar los valores por omisión de los contextos
@subsection Cambiar los valores por omisión de los contextos
@translationof Changing context default settings

Los ajustes de contexto que están preparados para usarse de forma
predeterminada en los contextos @code{Score}, @code{Staff} y
@code{Voice}, se pueden especificar dentro de un bloque
@code{\layout}, como se ilustra en el ejemplo siguiente.  El bloque
@code{\layout} se debe colocar dentro del bloque @code{\score} en que
se quiere que haga efecto, pero fuera de la música.

Observe que la propia instrucción @code{\set} y el contexto se deben
omitir cuando se especifican de esta manera los valores de contexto
predeterminados:

@lilypond[quote,verbatim]
\score {
  \relative c'' {
    a4^"Really small, thicker stems, no time signature" a a a
    a a a a
  }
  \layout {
    \context {
      \Staff
      fontSize = #-4
      \override Stem #'thickness = #4.0
      \remove "Time_signature_engraver"
    }
  }
}
@end lilypond

En este ejemplo, la instrucción @code{\Staff} especifica que los
ajustes siguientes se apliquen a todos los pentagramas dentro del
bloque de partitura.

Se pueden realizar de forma similar modificaciones al contexto
@code{Score} o a todos los contextos @code{Voice}.

@knownissues

No es posible recolectar cambios de contexto dentro de una variable y
aplicarlos a una definición de @code{\context} por referencia a dicha
variable.

La instrucción @code{\RemoveEmptyStaffContext} sobreescribe nuestros
ajustes en curso para @code{\Staff}.  Si queremos cambiar los valores
predeterminados para un pentagrama que utilice
@code{\RemoveEmptyStaffContext}, debe hacerlo después de llamar a
@code{\RemoveEmptyStaffContext}, o sea

@example
\layout @{
  \context @{
    \RemoveEmptyStaffContext

    \override Stem #'thickness = #4.0
  @}
@}
@end example

@c TODO: add \with in here.



@node Definir contextos nuevos
@subsection Definir contextos nuevos
@translationof Defining new contexts

@cindex contextos, definición de nuevos
@cindex grabadores, incluir en contextos

@funindex \alias
@funindex alias
@funindex \name
@funindex name
@funindex \type
@funindex type
@funindex \consists
@funindex consists
@funindex \accepts
@funindex accepts
@funindex \denies
@funindex denies

Los contextos específicos, como @code{Staff} y @code{Voice}, están
construidos a base de bloques sencillos.  Es posible crear nuevos
tipos de contextos con combinaciones distintas de añadidos grabadores.

El siguiente ejemplo muestra cómo construir un tipo diferente de
contexto de @code{Voice} partiendo de cero.  Será parecido a
@code{Voice}, pero imprime solamente cabezas centradas en forma de
barra inclinada.  Se puede usar para indicar improvisación en piezas
de jazz,

@c KEEP LY
@lilypond[quote,ragged-right]
\layout { \context {
  \name ImproVoice
  \type "Engraver_group"
  \consists "Note_heads_engraver"
  \consists "Rhythmic_column_engraver"
  \consists "Text_engraver"
  \consists Pitch_squash_engraver
  squashedPosition = #0
  \override NoteHead #'style = #'slash
  \override Stem #'transparent = ##t
  \alias Voice
}
\context { \Staff
  \accepts "ImproVoice"
}}

\relative c'' {
  a4 d8 bes8 \new ImproVoice { c4^"ad lib" c
   c4 c^"desvístete" c_"mientras tocas :)" c }
  a1
}
@end lilypond


Estos ajustes se definen dentro de un bloque @code{\context} que a su
vez está dentro de un bloque @code{\layout},

@example
\layout @{
  \context @{
    @dots{}
  @}
@}
@end example

En el siguiente análisis, la entrada de ejemplo que se muestra debe ir
en el lugar de los puntos suspensivos @dots{} del fragmento anterior.

En primer lugar es necesario definir un nombre para el nuevo contexto:

@example
\name ImproVoice
@end example

Debido a que es parecido al contexto @code{Voice}, queremos órdenes
que funcionen sobre contextos de @code{Voice} (existentes) para que
siga funcionando.  Esto se consigue dando al contexto nuevo un alias
@code{Voice},

@example
\alias Voice
@end example

El contexto imprimirá notas y textos explicativos, por ello tenemos
que añadir los grabadores que aportan esta funcionalidad:

@example
\consists Note_heads_engraver
\consists Text_engraver
@end example

pero sólo necesitamos esto en la línea central:

@example
\consists Pitch_squash_engraver
squashedPosition = #0
@end example

El grabador @rinternals{Pitch_squash_engraver} modifica las cabezas de
nota (creadas por el grabador @rinternals{Note_heads_engraver}) y
establece sus posiciones verticales al valor de
@code{squashedPosition}, en este caso@tie{}@code{0}, la línea central.

Las notas parecen barras inclinadas y no tienen plica:

@example
\override NoteHead #'style = #'slash
\override Stem #'transparent = ##t
@end example

Todos estos añadidos tienen que cooperar, y esto se consigue con un
añadido especial, que se debe marcar con la palabra clave
@code{\type}.  Este será siempre @code{Engraver_group},

@example
\type "Engraver_group"
@end example

Al juntarlo todo, obtenemos

@example
\context @{
  \name ImproVoice
  \type "Engraver_group"
  \consists "Note_heads_engraver"
  \consists "Text_engraver"
  \consists Pitch_squash_engraver
  squashedPosition = #0
  \override NoteHead #'style = #'slash
  \override Stem #'transparent = ##t
  \alias Voice
@}
@end example

@funindex \accepts
Los contextos dan lugar a jerarquías.  Queremos colgar el contexto
@code{ImproVoice} bajo el contexto @code{Staff}, como simples
@code{Voice}s normales.  Por tanto, modificamos la definición de
@code{Staff} con la instrucción @code{\accepts} (acepta),

@example
\context @{
  \Staff
  \accepts ImproVoice
@}
@end example

@funindex \denies
Lo opuesto a @code{\accepts} (acepta) es @code{\denies} (deniega), lo
que a veces se necesita cuando se están reutilizando definiciones de
contexto existentes.

Ponemos ambos dentro de un bloque @code{\layout}, como

@example
\layout @{
  \context @{
    \name ImproVoice
    @dots{}
  @}
  \context @{
    \Staff
    \accepts "ImproVoice"
  @}
@}
@end example

Así pues, la salida que aparece al comienzo de esta sub-sección se
puede escribir como

@example
\relative c'' @{
  a4 d8 bes8
  \new ImproVoice @{
    c4^"ad lib" c
    c4 c^"desvístete"
    c c_"mientras tocas :)"
  @}
  a1
@}
@end example


@node Alinear los contextos
@subsection Alinear los contextos
@translationof Aligning contexts

Los contextos nuevos se pueden alinear por encima o por debajo de
otros contextos existentes.  Esto podría ser de utilidad al preparar
un pentagrama vocal (@rlearning{Conjuntos vocales}) y en el ossia,

@cindex ossia
@funindex alignAboveContext
@funindex alignBelowContext

@lilypond[quote,ragged-right]
ossia = { f4 f f f }
\score{
  \relative c' \new Staff = "main" {
    c4 c c c
    <<
      \new Staff \with { alignAboveContext = #"main" } \ossia
      { d8 f d f d f d f }
    >>
  }
}
@end lilypond

@cindex nested contexts
@cindex contexts, nested

@funindex \accepts
@funindex \denies

Los contextos como @code{PianoStaff} pueden llevar dentro otros
contextos anidados.  Los contextos que se pueden aceptar para su
anidamiento están definidos por la lista @qq{accepts} (acepta) de un
contexto.  Los contextos que no están en esta lista se colocan debajo
del contexto exterior en la partitura impresa.  Por ejemplo, el
contexto @code{PianoStaff} está definido para que acepte contextos
@code{Staff} y @code{FiguredBass} de forma predeterminada, pero no un
contexto @code{Lyrics}, por ejemplo.  Así pues, en la siguiente
estructura la letra se sitúa debajo del sistema de piano en lugar de
colocarse entre los dos pentagramas:

@lilypond[verbatim,quote,relative=1]
\new PianoStaff
<<
  \new Staff { e4 d c2 }
  \addlyrics { Three blind mice }
  \new Staff {
    \clef "bass"
    { c,1 }
  }
>>
@end lilypond

La lista @qq{accepts} de un contexto se puede modificar para que
incluya contextos anidados adicionales, y así si quisiéramos que la
letra apareciese entre los dos pentagramas podríamos usar:

@lilypond[verbatim,quote,relative=1]
\new PianoStaff \with { \accepts Lyrics }
<<
  \new Staff { e4 d c2 }
  \addlyrics { Three blind mice }
  \new Staff {
    \clef "bass"
    { c,1 }
  }
>>
@end lilypond

Lo contrario de @code{\accepts} (acepta) es @code{\denies} (deniega);
esto suprime un contexto de la lista @qq{accepts}.


@node Explicación del Manual de referencia de funcionamiento interno
@section Explicación del Manual de referencia de funcionamiento interno
@translationof Explaining the Internals Reference


@menu
* Navegar por la referencia del programa::
* Interfaces de la presentación::
* Determinar la propiedad del grob::
* Convenciones de nombres::
@end menu



@node Navegar por la referencia del programa
@subsection Navegar por la referencia del programa
@translationof Navigating the program reference

Supongamos que queremos mover la indicación de digitación del
fragmento siguiente:

@lilypond[quote,fragment,relative=2,verbatim]
c-2
\stemUp
f
@end lilypond

Si hace una visita a la documentación en busca de instrucciones de
digitación (en @ref{Indicaciones de digitación}), encontrará:

@quotation
@strong{Véase también}

Referencia de funcionamiento interno: @rinternals{Fingering}.

@end quotation

@ifnothtml
La referencia del programador se encuentra disponible en forma de
documento HTML.  Se recomienda mucho que lo lea en la forma HTML, bien
en línea o bien descargando los archivos de la documentación HTML.
Esta sección sería mucho más difícil de entender si está utilizando el
manual en formato PDF.
@end ifnothtml

Siga el enlace que lleva a @rinternals{Fingering}.  Al principio de la
página, puede ver

@quotation
Los objetos de digitación se crean por parte de:
@rinternals{Fingering_engraver} y @rinternals{New_fingering_engraver}.
@end quotation

Siguiendo los enlaces relacionados dentro de la referencia del
programa, podemos seguir el flujo de información dentro del programa:

@itemize

@item @rinternals{Fingering}:
los objetos @rinternals{Fingering} se crean por parte de:
@rinternals{Fingering_engraver}

@item @rinternals{Fingering_engraver}:
Tipos de música aceptados: @rinternals{fingering-event}

@item @rinternals{fingering-event}:
El tipo de evento musical @code{fingering-event} está descrito en
Expresiones musicales con el nombre de @rinternals{FingeringEvent}
@end itemize

Este camino se recorre en contra de la corriente de información del
programa: comienza por la salida y acaba en el evento de entrada.
También podríamos haber empezado por un evento de la entrada, y leído
siguiendo el flujo de información terminando en su caso en el objeto
(u objetos) de la salida.

La referencia del programa también se puede examinar como un documento
normal.  Contiene capítulos que tratan de
@ifhtml
@rinternals{Music definitions},
@end ifhtml
@ifnothtml
@code{Music definitions}
@end ifnothtml
de la @rinternals{Translation}, y del @rinternals{Backend}.  Cada uno
de los capítulos relaciona todas las definiciones utilizadas y todas
las propiedades que se pueden ajustar.


@node Interfaces de la presentación
@subsection Interfaces de la presentación
@translationof Layout interfaces

@cindex interfaz de la presentación
@cindex presentación, interfaz de la
@cindex grob

La página HTML que pudimos ver en la sección anterior describe el
objeto de presentación llamado @rinternals{Fingering}.  Dicho objeto
es un símbolo dentro de la partitura.  Tiene propiedades que guardan
números (como grosores y direcciones), pero también punteros a objetos
relacionados.  Un objeto de presentación también se llama un
@emph{Grob}, que es una abreviatura de Graphical Object (objeto
gráfico).  Para ver más detalles acerca de los objetos gráficos o
Grobs, consulte @rinternals{grob-interface}.

La página dedicada a @code{Fingering} relaciona las definiciones del
objeto @code{Fingering}.  Por ejemplo, la página dice

@quotation
@code{padding} (dimensión, en espacios de pentagrama):

@code{0.5}
@end quotation

@noindent
lo que significa que el número se mantendrá a una distancia de al
menos 0.5 de la cabeza de la nota.


Cada objeto de presentación puede tener varias funciones como elemento
notacional o tipográfico.  Por ejemplo, el objeto de digitación
Fingering tiene los siguientes aspectos

@itemize
@item
Su tamaño es independiente del espaciado horizontal, al contrario de
las ligaduras o las barras de las figuras.

@item
Es un elemento de texto.  Casi seguro que es un texto muy corto.

@item
este elemento de texto se tipografía con un tipo de letra, no como las
ligaduras o las barras de las figuras.

@item
Horizontalmente, el centro del símbolo se debe alinear con el centro
de la cabeza de la nota.

@item
Verticalmente, el símbolo se coloca cerca de la nota y del pentagrama.

@item
La posición vertical también está coordinada con otros símbolos de
superíndice y de subíndice.
@end itemize

Cada uno de estos aspectos se capta en lo que se llaman
@emph{interface}s, que se relacionan al final de la página dedicada a
@rinternals{Fingering}

@quotation
Este objeto contempla los siguientes interfaces:
@rinternals{item-interface},
@rinternals{self-alignment-interface},
@rinternals{side-position-interface}, @rinternals{text-interface},
@rinternals{text-script-interface}, @rinternals{font-interface},
@rinternals{finger-interface} y @rinternals{grob-interface}.
@end quotation

Al pulsar sobre cualquiera de los enlaces nos desplazaremos a la
página del respectivo interfaz del objeto.  Cada interfaz tiene un
cierto número de propiedades.  Algunas de ellas no son para que el
usuario las pueda ajustar (@q{Propiedades internas}), pero otras sí se
pueden modificar.

Hemos estado hablando de @emph{el} objeto @code{Fingering}, pero
realmente esto no significa mucho.  El archivo de inicialización
(véase @rlearning{Otras fuentes de información})
@file{scm/@/define@/-grobs@/.scm} muestra el alma del @q{objeto},

@example
(Fingering
  . ((padding . 0.5)
     (avoid-slur . around)
     (slur-padding . 0.2)
     (staff-padding . 0.5)
     (self-alignment-X . 0)
     (self-alignment-Y . 0)
     (script-priority . 100)
     (stencil . ,ly:text-interface::print)
     (direction . ,ly:script-interface::calc-direction)
     (font-encoding . fetaNumber)
     (font-size . -5)           ; don't overlap when next to heads.
     (meta . ((class . Item)
     (interfaces . (finger-interface
                    font-interface
                    text-script-interface
                    text-interface
                    side-position-interface
                    self-alignment-interface
                    item-interface))))))
@end example

@noindent
Como podemos ver, el objeto @code{Fingering} no es más que un montón
de valores de variables, y la página web de la Referencia de
funcionamiento interno se genera directamente a partir de esta
definición.


@node Determinar la propiedad del grob
@subsection Determinar la propiedad del grob
@translationof Determining the grob property

Recordemos que queríamos cambiar la posición del @b{2} en

@lilypond[quote,fragment,relative=2,verbatim]
c-2
\stemUp
f
@end lilypond

Puesto que el @b{2} se encuentra colocado verticalmente sobre su nota,
tenemos que negociar con el interfaz asociado con esta colocación.
Esto se hace usando @code{side-position-interface}.  La página que
describe este interface dice:

@quotation
@code{side-position-interface}

Colocar un objeto víctima (este mismo) junto a otros objetos (el
soporte).  La propiedad @code{direction} significa dónde poner el
objeto víctima con relación al soporte (¿a la izquierda o a la
derecha, encima o debajo?)
@end quotation

@cindex relleno
@cindex padding (relleno)
@noindent
Debajo de esta descripción, la variable @code{padding} (relleno) se
describe como

@quotation
@table @code
@item padding
(dimensión, en espacios de pentagrama)

Añadir esta cantidad de espacio adicional entre objetos que están unos
junto a otros.
@end table
@end quotation

Aumentando el valor de @code{padding}, podemos alejar la cifra de
digitación de la cabeza de la nota.  La siguiente orden inserta un
espacio en blanco de 3 espacios de pentagrama entre la nota y la
digitación:
@example
\once \override Voice.Fingering #'padding = #3
@end example

Al insertar esta instrucción antes de que se haya creado el objeto
Fingering, es decir, antes del @code{c2}, llegamos al siguiente
resultado:

@lilypond[quote,relative=2,fragment,verbatim]
\once \override Voice.Fingering #'padding = #3
c-2
\stemUp
f
@end lilypond

En este caso, el contexto de este truco es @code{Voice}.  Este hecho
se puede deducir también a partir de la referencia del programa, ya
que la página dedicada al añadido @rinternals{Fingering_engraver} dice

@quotation
El grabador Fingering_engraver es parte de los contextos: @dots{}
@rinternals{Voice}
@end quotation


@node Convenciones de nombres
@subsection Convenciones de nombres
@translationof Naming conventions

Se hace necesario presentar una panorámica de las diversas
convenciones de nomenclatura:

@itemize
@item funciones de Scheme: minúsculas-con-guiones (incluso nombres de una sola palabra)
@item funciones de Scheme: ly:más-estilo-de-scheme
@item eventos, clases y propiedades musicales: como-las-funciones-de-scheme
@item interfaces de Grobs: estilo-scheme
@item propiedades de backend: estilo-scheme (¡pero X e Y en mayúsculas!)
@item contextos (y ExpresionesMusicales y grobs): Mayúsculas o MayúsculasDeCamello
@item propiedades de contexto: minúsculasSeguidoDeMayúsculasDeCamello
@item grabadores: Mayúsculas_seguido_de_minúsculas_y_con_barras_bajas
@end itemize

@ignore
Preguntas aún sin respuesta
@itemize
@item ¿Cuáles de aquéllas son convenciones y cuáles son reglas?
@item ¿Cuáles son reglas del lenguaje subyacente, y cuáles son específicas de LilyPond?
@end itemize
@end ignore

@node Modificar las propiedades
@section Modificar las propiedades
@translationof Modifying properties

@menu
* Panorámica de la modificación de las propiedades::
* La instrucción set::
* La instrucción override::
* La instrucción tweak::
* set frente a override::
@end menu


@node Panorámica de la modificación de las propiedades
@subsection Panorámica de la modificación de las propiedades
@translationof Overview of modifying properties

Cada contexto es responsable de la creación de ciertos tipos de
objetos gráficos.  Los ajustes que se usan para imprimir estos objetos
también se almacenan por contexto.  Mediante la modificación de estos
ajustes, se puede alterar la apariencia de los objetos.

Existen dos tipos diferentes de propiedades almacenadas en los
contextos: las propiedades de contexto y las propiedades de grob.  Las
prpopiedades de contexto son propiedades que se aplican al contexto
como un todo y controlan la forma en que el propio contexto se
imprime.  Por contra, las propiedades de grob se aplican a los tipos
de grob específicos que se imprimirán dentro del contexto.

Las instrucciones @code{\set} y @code{\unset} se usan para cambiar los
valores de las propiedades de contexto.  Las instrucciones
@code{\override} y @code{\revert} se usan para cambiar los valores de
las propiedades de grob.

@ignore
La sintaxis de esto es

@example
\override @var{contexto}.@var{nombre} #'@var{propiedad} = #@var{valor}
@end example

Aquí @var{nombre} es el nombre de un objeto gráfico, como @code{Stem}
o @code{NoteHead}, y @var{propiedad} es una variable interna del
sistema de formateo (@q{propiedad del grob} o @q{propiedad de
disposición}).  Este último es un símbolo, y por ello debe ir
precedido de un apóstrofo.  La subsección @ref{Modificar las propiedades}
explica cómo se deben cumplimentar los conceptos @var{nombre},
@var{propiedad} y @var{valor}.  Aquí sólo nos ocuparemos de la
funcionalidad des esta instrucción.

La instrucción

@verbatim
\override Staff.Stem #'thickness = #4.0
@end verbatim

@noindent
hace más gruesas las plicas (el valor predeterminado es 1.3, con el
grosor de una línea del pentagrama como unidad).  Puesto que la
instrucción especifica como contexto a @code{Staff}, sólo se aplica al
pentagrama actual.  Otros pentagramas mantienen su aspecto normal.
Aquí vemos la instrucción en pleno funcionamiento:

@lilypond[quote,verbatim,relative=2,fragment]
c4
\override Staff.Stem #'thickness = #4.0
c4
c4
c4
@end lilypond

La instrucción @code{\override} modifica la definición de la plica
@code{Stem} dentro del pentagrama en curso @code{Staff}.  Después de
que la instrucción se ha interpretado, todas las plicas se engrosan.

De manera análoga a @code{\set}, el argumento @var{contexto} se puede
omitir, ocasionando que se utilice el contexto predeterminado
@code{Voice}.  Al añadir @code{\once} se aplica el cambio durante un
solo paso de tiempo.

@lilypond[quote,fragment,verbatim,relative=2]
c4
\once \override Stem #'thickness = #4.0
c4
c4
@end lilypond

El @code{\override} se debe hacer antes de que el objeto se inicia.
Por tanto, al alterar objetos @emph{Spanner} «de extensión» como
ligaduras o barras, la instrucción @code{\override} se debe ejecutar
en el momento en que se crea el objeto.  En este ejemplo:

@lilypond[quote,fragment,verbatim,relative=2]
\override Slur #'thickness = #3.0
c8[( c
\override Beam #'thickness = #0.6
c8 c])
@end lilypond

@noindent
la ligadura es más gruesa pero la barra no lo es.  Esto es así porque
la instrucción para @code{Beam}, la barra, va después de que la barra
se ha iniciado, y por ello no tiene ningún efecto.

De forma análoga a @code{\unset}, la instrucción @code{\revert} para
un contexto deshace una instrucción @code{\override}; como con
@code{\unset}, solamente afecta a los ajustes que se hicieron dentro
del mismo contexto.  En otras palabras, el @code{\revert} del
siguiente ejemplo no hace nada.

@example
\override Voice.Stem #'thickness = #4.0
\revert Staff.Stem #'thickness
@end example

Algunas opciones «trucables» se llaman @q{subpropiedades} y residen
dentro de las propiedades normales.  Para trucarlas, utilice
instrucciones de la forma

@c leave this as a long long
@example
\override @var{context}.@var{name} #'@var{property} #'@var{subproperty} = #@var{value}
@end example

@noindent
tales como

@example
\override Stem #'(details beamed-lengths) = #'(4 4 3)
@end example

@end ignore

@seealso
Referencia de funcionamiento interno:
@rinternals{Backend},
@rinternals{All layout objects},
@rinternals{OverrideProperty},
@rinternals{RevertProperty},
@rinternals{PropertySet}.


@knownissues

El «back-end» o motor de salida no es muy estricto en la comprobación
de tipos de las propiedades de objetos.  Las referencias cíclicas en
valores Scheme de propiedades pueden producir cuelgues o salidas
abruptas, o las dos cosas.


@node La instrucción set
@subsection La instrucción @code{@bs{}set}
@translationof The set command

@cindex propiedades
@funindex \set
@cindex cambiar propiedades

Cada contexto puede tener distintas @emph{propiedades}, variables
contenidas dentro de ese contexto.  Se pueden cambiar mientras dura el
paso de interpretación.  Se consigue insertando la instrucción
@code{\set} dentro de la música:

@example
\set @var{contexto}.@var{propiedad} = #@var{valor}
@end example

@var{valor} es un objeto de Scheme, razón por la que va precedido del
carácter almohadilla, @code{#}.

El nombre de las propiedades de contexto suele ir en minúsculas con
mayúscula en medio.  Controlan sobre todo la traducción de la música a
la notación, p.ej. @code{localKeySignature} (para determinar si hay
que impriir alteraciones o no), o @code{measurePosition} (para
determinar cuándo hay que imprimir una línea divisoria).  El valor de
las propiedades de contexto puede modifcarse con el tiempo durante la
interpretación de la música; un ejemplo obvio es
@code{measurePosition}.  Las propiedades de contexto se modifican
mediante la instrucción @code{\set}.

Por ejemplo, los silencios multicompás se combinan en un solo compás
si el valor de la propiedad de contexto @code{skipBars} se establece a
@code{#t} (verdadero):

@lilypond[quote,verbatim,relative=2,fragment]
R1*2
\set Score.skipBars = ##t
R1*2
@end lilypond

Si se omite el argumento @var{context}, entonces se utiliza el
contexto actual de nivel más bajo (normalmente @code{ChordNames},
@code{Voice} o @code{Lyrics}). En este ejemplo:

@lilypond[quote,verbatim,relative=2,fragment]
\set Score.autoBeaming = ##f
<<
  {
    e8 e e e
    \set autoBeaming = ##t
    e8 e e e
  } \\ {
    c8 c c c c8 c c c
  }
>>
@end lilypond

El cambio se aplica @q{al vuelo}, mientras dura la música, de forma
que el ajuste sólo afecta al segundo grupo de corcheas.

Observe que el contexto del nivel más bajo no siempre contiene la
propiedad que querríamos modificar: por ejemplo, intentar ajustar el
valor de la propiedad @code{skipBars} del contexto predeterminado del
nivel más bajo, que en este caso es @code{Voice}, no tendrá ningún
efecto, porque skipBars es una propiedad del contexto @code{Score}.

@lilypond[quote,verbatim,relative=2,fragment]
R1*2
\set skipBars = ##t
R1*2
@end lilypond

Los contextos son jerárquicos, y si se ha especificado un contexto
mayor, por ejemplo @code{Staff}, entonces el cambio se aplicaría
también a todos los contextos @code{Voice} dentro del pentagrama
actual.

@funindex \unset

También existe una instrucción @code{\unset}:
@example
\unset @var{contexto}.@var{propiedad}
@end example

@noindent
que elimina la definición de @var{propiedad}.  Esta instrucción
elimina la definición solamente si está establecida dentro de
@var{contexto}.  Properties that have been set in enclosing contexts will
not be altered by an unset in an enclosed context:

@lilypond[quote,verbatim,relative=2,fragment]
\set Score.autoBeaming = ##t
<<
  {
    \unset autoBeaming
    e8 e e e
    \unset Score.autoBeaming
    e8 e e e
  } \\ {
    c8 c c c c8 c c c
  }
>>
@end lilypond

Como @code{\set}, el argumento @var{contexto} no se tiene que
especificar para un contexto del nivel más bajo, por lo que los dos
enunciados

@example
\set Voice.autoBeaming = ##t
\set autoBeaming = ##t
@end example

@noindent
son equivalentes si el contexto inferior en curso es @code{Voice}.


@cindex \once
Los ajustes que se aplican solamente a un único paso de tiempo se
pueden escribir con @code{\once}, por ejemplo en

@lilypond[quote,verbatim,relative=2,fragment]
c4
\once \set fontSize = #4.7
c4
c4
@end lilypond

En el manual de Referencia de funcionamiento interno hay una
descripción completa de todas las propiedades de contexto disponibles,
consulte
@ifhtml
@rinternals{Tunable context properties}.
@end ifhtml
@ifnothtml
Traducción @expansion{} Propiedades de contexto modificables por el
usuario.
@end ifnothtml

@seealso

Referencia de funcionamiento interno:
@rinternals{Tunable context properties}.


@cindex grob, propiedades de
@cindex propiedades de grob
@funindex \override

@node La instrucción override
@subsection La instrucción @code{\override}
@translationof The override command

Existe un tipo especial de propiedad de contexto: la descripción de
los grobs.  Las decscripciones de los grobs reciben un nombre en
@code{MayúsculasDeCamello} (empezando en mayúscula).  Contienen los
@q{ajustes predeterminados} para un tipo particular de grob, en forma
de lista asociativa.  Consulte @file{scm/@/define@/-grobs@/.scm} para
ver los ajustes de cada descripción de grob.  Las descripciones de
grob se modifican con @code{\override}.

@code{\override} es en realidad una forma abreviada;

@example
\override @var{contexto}.@var{NombreDelGrob} #'@var{propiedad} = #@var{valor}
@end example

@noindent
equivale más o menos a

@c  leave this long line -gp
@example
\set @var{contexto}.@var{NombreDelGrob}  =
  #(cons (cons '@var{propiedad} @var{valor})
         <valor anterior de @var{contexto}.@var{NombreDelGrob}>)
@end example

El valor de @code{contexto}.@code{NombreDelGrob} (la lista-A) se
utiliza para inicializar las propiedades de los grobs individuales.
Los grobs tienen propiedades, denominadas en el estilo de Scheme, con
@code{palabras-con-guiones}.  Los valores de las propiedades de grob
cambian durante el proceso de formateo: éste se realiza básicamente
calculando las propiedades utilizando funciones de @q{callback}
(pasadas como parámetro).

Por ejemplo, podemos aumentar el grosor de la plica de una figura
sobreescribiendo la propiedad @code{thickness} (grosor) del objeto
@code{Stem} (plica):

@lilypond[quote, verbatim, relative=2, fragment]
c4 c
\override Voice.Stem #'thickness = #3.0
c4 c
@end lilypond

Si no se ha especificado ningún contexto en la instrucción
@code{\override}, se utiliza el contexto del nivel inferior:

@lilypond[quote, verbatim, relative=2, fragment]
{ \override Staff.Stem #'thickness = #3.0
  <<
    {
      e4 e
      \override Stem #'thickness = #0.5
      e4 e
    } \\ {
      c4 c c c
    }
  >>
}
@end lilypond

@funindex \revert
@cindex reversión de sobreescrituras
@cindex sobreescrituras, reversión de

El efecto de una instrucción de sobreescritura @code{\override} se
puede deshacer con @code{\revert}:

@lilypond[quote, verbatim, relative=2, fragment]
c4
\override Voice.Stem #'thickness = #3.0
c4 c
\revert Voice.Stem #'thickness
c4
@end lilypond

Los efectos de @code{\override} y @code{\revert} se aplican a todos
los grobs del contexto afectado partiendo del momento actual y hacia
adelante:

@lilypond[quote, verbatim, relative=2, fragment]
{
  <<
    {
      e4
      \override Staff.Stem #'thickness = #3.0
      e4 e e
    } \\ {
      c4 c c
      \revert Staff.Stem #'thickness
      c4
    }
  >>
}
@end lilypond

@funindex \once
@cindex sobreescritura para un solo momento

Se puede usar @code{\once} con @code{\override} para afectar solamente
al instante de tiempo actual:

@lilypond[quote, verbatim, relative=2, fragment]
{
  <<
    {
      \override Stem #'thickness = #3.0
      e4 e e e
    } \\ {
      c4
      \once \override Stem #'thickness = #3.0
      c4 c c
    }
  >>
}
@end lilypond


@ignore
Las instrucciones que modifican la salida tienen por lo general un
aspecto como

@example
\override Voice.Stem #'thickness = #3.0
@end example

@noindent
Para construir este truco debemos determinar los siguientes datos:

@itemize
@item el contexto: aquí @code{Voice}.
@item el objeto de presentación: aquí @code{Stem}.
@item la propiedad de presentación: aquí @code{thickness}.
@item un valor adecuado: aquí @code{3.0}.
@end itemize

Ciertas opciones ajustables se denominan @q{subpropiedades} y residen
en el interior de las propiedades normales.  Para modificarlas utilice
instrucciones de la forma

@example
\override Stem #'(details beamed-lengths) = #'(4 4 3)
@end example

@cindex documentación interna
@cindex buscar objetos gráficos
@cindex gráficos, descripción de los objetos
@cindex trucos
@funindex \override
@cindex interna, documentación

Para muchas propiedades, independientemente del tipo de datos de la
propiedad, si se establece el valor de la propiedad a falso
(@code{##f}) se producirá su desactivación, ocasionando que LilyPond
ignore por completo dicha propiedad.  Esto es especialmente útil para
«apagar» propiedades de grobs (objetos gráficos) que de otra manera
causarían problemas.

Mostraremos a continuación cómo localizar esta información en el
manual de notación y en la referencia de funcionamiento interno.
@end ignore

@seealso

Referencia de funcionamiento interno:
@rinternals{Backend}

@node La instrucción tweak
@subsection La instrucción @code{\tweak}
@translationof The tweak command

@funindex \tweak
@cindex trucar

El cambio de las propiedades de grob mediante @code{\override} produce
la aplicación del cambio a todos los grobs dados en el contexto en el
momento en que se aplica dicho cambio.  Sin embargo, en ocasiones
podemos desear que los cambios se apliquen a un solo grob en lugar de
a todos los grobs del contexto afectado.  Esto se consigue con la
instrucción @code{\tweak}, que tiene la sintaxis siguiente:

@example
\tweak #'@code{propiedad-del-grob} #@code{valor}
@end example

La instrucción @code{\tweak} se aplica al objeto que viene
inmediatamente después de @code{valor} dentro del flujo musical.

@ignore
En ocasiones es posible tomar un atajo para realizar el ajuste fino de
los objetos gráficos.  Para objetos que resultan directamente de un
elemento de código de la entrada, puede usar la función @code{\tweak},
por ejemplo

@lilypond[relative=2,verbatim]
< c
  \tweak #'color #red
  d
  g
  \tweak #'duration-log #1
  a
> 4
-\tweak #'padding #8
-^
@end lilypond



Pero el uso principal de la instrucción @code{\tweak} es modificar
solamente uno de varios elementos de notación que dan comienzo en el
mismo momento musical, como las notas de un acorde, o corchetes de
tresillo que empiezan al mismo tiempo.

La instrucción @code{\tweak} fija una propiedad en el objeto que viene
a continuación de forma directa, sin necesidad de especificar el
nombre del grob o el contexto.  Para que esto funcione, es necesario
que la instrucción @code{\tweak} permanezca inmediatamente adyacente
al objeto al que se aplica, después de que el archivo de entrada se ha
convertido en un flujo musical.  Con frecuencia no es el caso, pues
muchos elementos adicionales se insertan en la corriente musical de
forma implícita.  Por ejemplo, cuando se procesa una nota que no forma
parte de un acorde, LilyPond inserta implícitamente un evento
@code{ChordEvent} antes de la nota, separando así el truco de la nota.
Sin embargo, si los símbolos de acorde se sitúan cerca del truco y la
nota, la instrucción @code{\tweak} viene después del @code{ChordEvent}
en el flujo musical, permaneciendo así adyacente a la nota, y con la
posibilidad de modificarla.

Así, esto funciona:

@lilypond[relative=2,verbatim,quote]
<\tweak #'color #red c>4
@end lilypond

@noindent
pero esto no funciona:

@lilypond[relative=2,verbatim,quote]
\tweak #'color #red c4
@end lilypond

@end ignore

Para ver una introducción a la sintaxis y los usos de la instrucción tweak,
consulte @rlearning{Métodos de trucaje}.

Si se colocan varios elementos similares en el mismo momento musical,
la instrucción @code{\override} no se puede usar para modificar uno
solo de ellos: aquí es donde se debe usar la instrucción
@code{\tweak}.  Entre los elementos que pueden aparecer más de una vez
en el mismo momento musical están los siguientes:

@c TODO expand to include any further uses of \tweak
@itemize
@item las cabezas de las notas de un acorde
@item signos de articulación sobre la misma nota
@item ligaduras de unión entre notas de un acorde
@item corchetes de grupos especials que comienzan en el mismo momento
@end itemize

@c TODO add examples of these

@cindex acorde, modificación de una nota

En este ejemplo se modifican el color de una cabeza y el tipo de otra,
dentro del mismo acorde:

@lilypond[relative=2,verbatim,quote]
< c
  \tweak #'color #red
  d
  g
  \tweak #'duration-log #1
  a
> 4
@end lilypond

@code{\tweak} se puede usar para modificar ligaduras de expresión:

@lilypond[verbatim,quote,relative=1]
c-\tweak #'thickness #5 ( d e f)
@end lilypond


Para que funcione la instrucción @code{\tweak}, debe permanecer
adyacente al objeto al que se ha de aplicar después de que el código
de entrada se ha convertido a un flujo musical.  A veces, LilyPond
puede insertar elementos adicionales dentro del flujo de música
durante el proceso de análisis sintáctico.  Por ejemplo, cuando una
nota que no es parte explícita de un acorde se coloca dentro de un
acorde por parte de LilyPond de manera que las notas que se pretenden
modificar con @code{\tweak} se deben poner dentro de una construcción
de acorde:

@lilypond[relative=2,verbatim,quote]
\tweak #'color #red c4
<\tweak #'color #red c>4
@end lilypond

La instrucción @code{\tweak} no se puede usar para modificar ningún
elemento que no aparezca explícitamente en el código de entrada.
Concretamente, no se puede usar para modificar plicas, barras o
alteraciones directamente, porque éstos se generan posteriormente por
parte de las cabezas de las notas, más que por elementos musicales del
flujo de entrada.  Tampoco se puede usar @code{\tweak} para modificar
las claves ni las indicaciones de compás, porque se separarán de
cualquier instrucción @code{\tweak} que aparezca en el flujo de
entrada debido a la inserción automática de los elementos adicionales
que se requieren para especificar el contexto.

También se pueden escribir varias instrucciones @code{\tweak} antes de
un elemento notacional, y todas ellas le afectan:

@lilypond[verbatim,quote,relative=1]
c
-\tweak #'style #'dashed-line
-\tweak #'dash-fraction #0.2
-\tweak #'thickness #3
-\tweak #'color #red
 \glissando
f'
@end lilypond

El flujo musical que se genera a partir de una sección de un archivo
de entrada (incluido cualquier elemento insertado automáticamente)
puede examinarse, véase @rextend{Presentación de las expresiones
musicales}.  Esto puede ser de utilidad en la determinación de lo que
puede modificarse por medio de una instrucción @code{\tweak}.


@seealso
Manual de aprendizaje:
@rlearning{Métodos de trucaje}.

Manual de extensión:
@rextend{Presentación de las expresiones musicales}.


@knownissues

@cindex trucos en una variable
La instrucción @code{\tweak} no se puede usar dentro de una variable.

@cindex trucos en la letra
Las instrucciones @code{\tweak} no se pueden usar dentro del modo
@code{\lyricmode}.

@cindex trucar puntos de control
@cindex control, trucar puntos de

La instrucción @code{\tweak} solamente se aplica a la primera de
varias ligaduras generadas dentro de un acorde.

@node set frente a override
@subsection @code{\set} frente a @code{\override}
@translationof set versus override

HACER: probablemente esta sección es innecesaria.

@ignore
We have seen two methods of changing properties: @code{\set} and
@code{\override}.  There are actually two different kinds of
properties.

@code{fontSize} is a special property: it is equivalent to
entering @code{\override ... #'font-size} for all pertinent
objects.  Since this is a common change, the special
property (modified with @code{\set}) was created.

@end ignore

@node Conceptos y propiedades útiles
@section Conceptos y propiedades útiles
@translationof Useful concepts and properties


@menu
* Modos de entrada::
* Dirección y posición::
* Orden de disposición de los contextos::
* Distancias y medidas::
* Propiedades del símbolo del pentagrama::
* Objetos de extensión::
* Visibilidad de los objetos::
* Estilos de línea::
* Rotación de objetos::
@end menu

@node Modos de entrada
@subsection Modos de entrada
@translationof Input modes

La forma en que se interpreta la notación contenida dentro de un
archivo de entrada, está determinada por el modo de entrada en curso.

@strong{Modo de acordes}

Se activa con la instrucción @code{\chordmode} y produce que la
entrada se interprete con al sintaxis de la notación de acordes, véase
@ref{Notación de acordes}.  Los acordes se imprimen como notas sobre un
pentagrama.

El modo de acordes se activa también con la instrucción
@code{\chords}.  Esto crea también un contexto @code{ChordNames} nuevo
y produce que el código que sigue se interprete con la sintaxis de la
notación de acordes y se imprima como nombres de acorde dentro del
contexto @code{ChordNames}, véase @ref{Impresión de los nombres de acorde}.

@strong{Modo de percusión}

Se activa con la instrucción @code{\drummode} y produce que el código
de entrada se interprete con la sintaxis de la notación de percusión,
véase @ref{Notación básica de percusión}.

El modo de percusión también se activa con la instrucción
@code{\drums}.  También crea un contexto @code{DrumStaff} nuevo y hace
que el código que sigue se interprete con la sintaxis de la notación
de percusión y se imprima como símbolos de percusión sobre un
pentagrama de percusión, véase @ref{Notación básica de percusión}.

@strong{Modo de cifras}

Se activa con la instrucción @code{\figuremode} y hace que el código
de entrada se interprete con la sintaxis del bajo cifrado, véase
@ref{Introducir el bajo cifrado}.

El modo de cifrase también se activa con la instrucción
@code{\figures}.  También crea un contexto de @code{FiguredBass} nuevo
y hace que el código que viene a continuación se interprete con la
sintaxis del bajo cifrado y se imprima como símbolos de bajo cifrado
dentro del contexto @code{FiguredBass}, véase @ref{Introducción al bajo cifrado}.

@strong{Modos de traste y tablatura}

No existen modos de entrada especiales para introducir símbolos de
trastes y de tablatura.

Para crear diagramas de trastes, escriba las notas o acordes en el
modo de notas e imprímalos dentro de un contexto @code{TabStaff},
véase @ref{Tablaturas predeterminadas}.

Para crear diagramas de trastes encima de un pentagrama, escríbalos
como elementos de marcado encima de las notas utilizando la
instrucción @code{\fret-diagram}, véase @ref{Marcas de diagramas de trastes}.

@strong{Modo de letra}

Se activa con la instrucción @code{\lyricmode}, y hace que la entrada
se interprete como sílabas de la letra de la canción con duraciones
opcionales y modificadores de letra asociados, véase @ref{Música vocal}.

El modo de letra también se habilita con la instrucción
@code{\addlyrics}.  Esto también crea un contexto @code{Lyrics} nuevo
y una instrucción @code{\lyricsto} implícita que asocia la letra que
viene a continuación con la música precedente.

@strong{Modo de marcado}

Se activa con la instrucción @code{\markup}, y hace que la entrada se
interprete con la sintaxis del marcado, véase @ref{Text markup commands}.

@c silly work-around for texinfo broken-ness
@c (@strong{Note...} causes a spurious cross-reference in Info)
@b{Modo de notas}

Es el modo predeterminado o se puede activar con la instrucción
@code{\notemode}.  La entrada se interpreta como alturas, duraciones,
marcado, etc. y se imprime como notación musical sobre un pentagrama.

Normalmente no es necesario especificar el modo de notas de forma
explícita, pero puede ser útil hacerlo en ciertas situaciones, por
ejemplo si estamos en el modo de letra, en el modo de acordes o en
otro modo y queremos insertar algo que solamente se puede hacer con la
sintaxis del modo de notas.

Por ejemplo, para insertar indicaciones dinámicas para las estrofas de
una pieza coral es necesario entrar en el modo de notas para poder
interpretar dichas indicaciones:

@lilypond[verbatim,relative=2,quote]
{ c4 c4 c4 c4 }
\addlyrics {
  \notemode{\set stanza = \markup{ \dynamic f 1. } }
  To be sung loudly
}
\addlyrics {
  \notemode{\set stanza = \markup{ \dynamic p 2. } }
  To be sung quietly
}
@end lilypond



@node Dirección y posición
@subsection Dirección y posición
@translationof Direction and placement

Al tipografiar música, la dirección y colocación de muchos elementos
es cuestión de elección.  Por ejemplo, las plicas de las notas se
pueden dirigir hacia arriba o hacia abajo; la letra, las indicaciones
dinámicas y otras marcas expresivas se pueden colocar encima o debajo
del pentagrama; el texto se pude alinear a la izquierda, a la derecha
o centrado; etc.  La mayoría de estas elecciones pueden dejarse que
LilyPond las determine automáticamente, pero en ciertos casos puede
ser deseable forzar una dirección o colocación concreta.

@strong{Acciones predeterminadas}

De forma predeterminada algunas direcciones siempre son hacia arriba o
siempre hacia abajo (p. ej. los matices o el calderón), mientras que
otras cosas pueden alternar entre arriba y abajo en función de la
dirección de las plicas (como las ligaduras o los acentos).

@c TODO Add table showing these

@strong{Disposición de contexto}

Los contextos se colocan dentro de un sistema de arriba a abajo en el
orden en que se encuentran.  Sin embargo, observe que se crea un
contexto implícitamente si se encuentra una instrucción cuando no está
disponible un contexto apropiado para contenerla.

@c TODO Add example ?

Se pude cambiar el orden predeterminado en que los contextos se
presentan, véase @ref{Alinear los contextos}

@strong{Indicadores de dirección de las articulaciones}

Al añadir articulaciones a notas se puede omitir normalmente el
indicador de dirección, @code{^} (que significa @qq{arriba}), @code{_}
(que significa @qq{abajo}) o @code{-} (que significa @qq{usar la
dirección predeterminada}), en cuyo caso se supone el predeterminado
@code{-}.  Pero se necesita un indicador de dirección @strong{siempre}
antes de:

@itemize
@item las instrucciones @code{\tweak}
@item las instrucciones @code{\markup}
@item las instrucciones @code{\tag}
@item los marcados de cadena, p.ej. -"cadena"
@item las instrucciones de digitación, p.ej. @code{-1}
@item las abreviaturas de articulación, p.ej. @code{-.}, @code{->}, @code{--}
@end itemize

Estas indicaciones afectan sólo a la nota siguiente.

@lilypond[verbatim,quote,relative=2]
c2( c)
c2_( c)
c2( c)
c2^( c)
@end lilypond

@strong{La propiedad de dirección}

La posición o dirección de muchos objetos de presentación está
controlada por la propiedad @code{direction}.

El valor de la propiedad @code{direction} se puede establecer al valor
@code{1}, con el significado de @qq{hacia arriba} o @qq{encima}, o a
@code{-1}, con el significado de @qq{hacia abajo} o @qq{debajo}.  Se
pueden usar los símbolos @code{UP} y @code{DOWN} en sustitución de
@code{1} y @code{-1} respectivamente.  La dirección predeterminada se
puede especificar estableciendo @code{direction} a @code{0} ó a
@code{CENTER}.  De forma alternativa, en muchos casos existen
instrucciones predefinidas para especificar la dirección.  Todas ellas
son de la forma:

@noindent
@code{\xxxUp}, @code{xxxDown}, @code{xxxNeutral}

@noindent
donde @code{xxxNeutral} significa @qq{utilizar la dirección
predeterminada}.  Véase @rlearning{Objetos interiores al pentagrama}.

En alguna que otra ocasión, con el único ejemplo usual del arpegio, el
valor de la propiedad @code{direction} especifica si el objeto se debe
colocar a la izquierda o a la derecha del objeto padre.  En este caso
@code{-1} ó @code{LEFT} significan @qq{a la izquierda} y @code{1} ó
@code{RIGHT} significan @qq{a la derecha}.  @code{0} ó @code{CENTER}
significan @qq{utilizar la dirección predeterminada}, como antes.

Estas indicaciones afectan a todas las notas hasta que son canceladas.

@lilypond[verbatim,quote,relative=2]
c2( c)
\slurDown
c2( c)
c2( c)
\slurNeutral
c2( c)
@end lilypond


@node Orden de disposición de los contextos
@subsection Orden de disposición de los contextos
@translationof Context layout order

@cindex contextos, orden de disposición

Los contextos se disponen en un sistema normalmente desde arriba hacia
abajo en el orden en que se encuentran en el archivo de entrada.
Cuando los contextos se anidan unos dentro de otros, el contexto
exterior incluye a los contextos anidados tal y como se especifica en
el archivo de entrada, siempre y cuando los contextos interiores estén
incluidos en la lista @qq{accepts} del contexto externo.  Los
contextos anidados que no está nincluidos en la lista @qq{accepts} del
contexto externo se recolocan debajo del contexto externo en lugar de
anidarse dentro de él.

Observe que discretamente se crea un contexto de forma implícita si se
encuentra una instrucción donde no hay un contexto apropiado para
contenerlo.  Esto puede dar lugar a pentagramas o partituras nuevos no
esperados.

El orden predeterminado en que los contextos se disponen, así como la
lista @qq{accepts}, pueden cambiarse; véase @ref{Alinear los
contextos}.

@seealso
Manual de utilización del programa:
@rprogram{Aparece un pentagrama de más}.

@node Distancias y medidas
@subsection Distancias y medidas
@translationof Distances and measurements

@cindex distancias absolutas
@cindex distancias escaladas

@funindex \mm
@funindex \cm
@funindex \in
@funindex \pt

Las distancias en LilyPond son de dos tipos: absolutas y escaladas.

Las distancias absolutas se usan para especificar márgenes, sangrados
y otros detalles de diseño de página, y de forma predeterminada se
especifican en milímetros.  Las distancias se pueden especificar en
otras unidades escribiendo después de la cifra indicativa de la
cantidad, @code{\mm}, @code{\cm}, @code{\in}@tie{}(pulgadas), o
@code{\pt}@tie{}(puntos, 1/72.27 pulgadas).  Las distancias de diseño
de página se pueden especificar también en unidades escalables (véase
el párrafo siguiente) adjuntando @code{\staff-space} a la cantidad.
La disposición de página se describe en detalle en @ref{Formateo de
las páginas}.

Las distancias escaladas siempre se especifican en unidades de un
espacio del pentagrama o, más raramente, medio espacio del pentagrama.
El espacio de pentagrama es la distancia entre dos líneas del
pentagrama adyacentes.  El valor predeterminado se puede cambiar
globalmente fijando el tamaño global del pentagrama, o se puede
sobreescribir localmente cambiando la propiedad @code{staff-space} del
objeto @code{StaffSymbol}.  Las distancias escaladas se escalan
automáticamente con cualquier cambio al tamaño global del pentagrama o
a la propiedad @code{staff-space} del objeto @code{StaffSymbol}, pero
las fuentes tipográficas se escalan solamente con los cambios
efectuados al tamaño global del pentagrama.  Así, el tamaño global del
pentagrama posibilita la fácil variación del tamaño general de una
partitura impresa.  Para ver los métodos de establecimiento del tamaño
global del pentagrama, véase @ref{Establecer el tamaño del pentagrama}.

@funindex magstep

Si se necesita dibujar sólo una sección de una partitura a una escala
distinta, por ejemplo una sección ossia o una nota al pie, no se puede
simplemente cambiar el tamaño global del pentagrama porque esto
afectaría a toda la partitura.  En tales casos, el cambio de tamaño se
hace sobreescribiendo tanto la propiedad @code{staff-space} de
@code{StaffSymbol} como el tamaño de las fuentes tipográficas.  Está a
nuestra disposición una función de Scheme, @code{magstep}, para
convertir de un cambio en el tamaño de la fuente al cambio equivalente
en @code{staff-space}.  Para ver una explicación y un ejemplo de su
utilización, consulte @rlearning{Longitud y grosor de los objetos}.


@seealso
Manual de aprendizaje:
@rlearning{Longitud y grosor de los objetos}.

Referencia de la notación:
@ref{Formateo de las páginas},
@ref{Establecer el tamaño del pentagrama}.


@node Propiedades del símbolo del pentagrama
@subsection Propiedades del símbolo del pentagrama
@translationof Staff symbol properties

@cindex ajuste del símbolo del pentagrama
@cindex dibujar el símbolo del pentagrama
@cindex pentagrama, establecer el símbolo del

@c TODO Extend or remove this section.  See also NR 1.6.2 Staff symbol
@c      Need to think of uses for these properties.  Eg 'line-positions
@c      is used in a snippet to thicken centre line.
@c      If retained, add @ref to here in 1.6.2  -td

Se puede definir al mismo tiempo la posición vertical de las líneas de
la pauta y el número de líneas de la misma.  Como muestra el siguiente
ejemplo, las posiciones de las notas no están influidas por las
posiciones de las líneas de la pauta.

@warning{La propiedad @code{'line-positions} sobreescribe a la
propiedad @code{'line-count}.  El número de líneas de la pauta está
definido implícitamente por el número de elementos de la lista de
valores de @code{'line-positions}.}

@lilypond[verbatim,quote,relative=1]
\new Staff \with {
  \override StaffSymbol #'line-positions = #'(7 3 0 -4 -6 -7)
}
{ a4 e' f b | d1 }
@end lilypond

Se puede modificar la anchura de la pauta.  Las unidades son espacios
de pentagrama.  El espaciado de los objetos dentro del pentagrama no
resulta afectado por este ajuste.

@lilypond[verbatim,quote,relative=1]
\new Staff \with {
  \override StaffSymbol #'width = #23
}
{ a4 e' f b | d1 }
@end lilypond


@node Objetos de extensión
@subsection Objetos de extensión
@translationof Spanners

Muchos objetos de notación musical abarcan varias notas o incluso
varios compases.  Son ejemplos los crescendi, trinos, corchetes de
grupo especial y corchetes de primera y segunda vez.  Estos objetos se
llaman @qq{spanners} u «objetos de extensión», y tienen propiedades
especiales para controlar su apariencia y comportamiento.  Algunas de
estas propiedades son comunes a todos los objetos de extensión; otras
se limitan a un subconjunto de los extensores.

Todos los objetos de extensión contemplan el interface
@code{spanner-interface}.  Algunos, básicamente aquellos que trazan
una línea recta entre los dos objetos, contemplan también el interface
@code{line-spanner-interface}.

@unnumberedsubsubsec Uso del @code{spanner-interface}

Este interface proporciona dos propiedades que se aplican a varios
extensores.

@strong{@i{La propiedad @code{minimum-length}}}

La longitud mínima del objeto de extensión se especifica a través de
la propiedad @code{minimum-length}.  Su aumento suele producir el
efecto necesario de aumentar el espaciado de las notas entre los dos
puntos extremos.  Sin embargo, esta sobreescritura no tiene ningún
efecto sobre muchos extensores, pues su longitud está determinada por
otras consideraciones.  Más abajo se muestran algunos ejemplos de
dónde es efectiva.

@ignore
Works for:
  Tie
  MultiMeasureRest
  Hairpin
  Slur
  PhrasingSlur

Works as long as callback is made:
  Glissando
  Beam

Works not at all for:
  LyricSpace
  LyricHyphen
  LyricExtender
  TextSpanner
  System

@end ignore

@lilypond[verbatim,quote,relative=2]
a~a
a
% increase the length of the tie
-\tweak #'minimum-length #5
~a
@end lilypond

@lilypond[verbatim,quote,relative=2]
a1
\compressFullBarRests
R1*23
% increase the length of the rest bar
\once \override MultiMeasureRest #'minimum-length = #20
R1*23
a1
@end lilypond

@lilypond[verbatim,quote,relative=2]
a \< a a a \!
% increase the length of the hairpin
\override Hairpin #'minimum-length = #20
a \< a a a \!
@end lilypond

Esta sobreescritura se puede usar también para aumentar la longitud de
las ligaduras de expresión y de fraseo:

@lilypond[verbatim,quote,relative=2]
a( a)
a
-\tweak #'minimum-length #5
( a)

a\( a\)
a
-\tweak #'minimum-length #5
\( a\)
@end lilypond

Para algunos objetos de presentación, la propiedad
@code{minimum-length} es efectiva sólo si se llama explícitamente al
procedimiento @code{set-spacing-rods}.  Para hacerlo, se debe fijar la
propiedad @code{springs-and-rods} al valor
@code{ly:spanner::set-spacing-rods}.  Por ejemplo, la longitud mínima
de un glissando no tiene efecto a no ser que se establezca la
propiedad @code{springs-and-rods}:

@lilypond[verbatim,quote,relative=1]
% default
e \glissando c'

% not effective alone
\once \override Glissando #'minimum-length = #20
e, \glissando c'

% effective only when both overrides are present
\once \override Glissando #'minimum-length = #20
\once \override Glissando #'springs-and-rods = #ly:spanner::set-spacing-rods
e, \glissando c'
@end lilypond

Lo mismo se puede decir del objeto @code{Beam}:

@lilypond[verbatim,quote,relative=1]
% not effective alone
\once \override Beam #'minimum-length = #20
e8 e e e

% effective only when both overrides are present
\once \override Beam #'minimum-length = #20
\once \override Beam #'springs-and-rods = #ly:spanner::set-spacing-rods
e8 e e e
@end lilypond

@strong{@i{The @code{to-barline} property}}

La segunda propiedad útil del @code{spanner-interface} es
@code{to-barline}.  De forma predeterminada tiene el valor cierto,
haciendo que los reguladores y otros objetos de extensión que terminan
sobre la primera nota de un compás, en vez de eso terminen en la línea
divisoria inmediatamente precedente.  Si se establece al valor falso,
el extensor llegará más allá de la barra de compás y terminará
exactamente sobre la nota:

@lilypond[verbatim,quote,relative=2]
a \< a a a a \! a a a \break
\override Hairpin #'to-barline = ##f
a \< a a a a \! a a a
@end lilypond

Esta propiedad no es efectiva para todos los extensores.  Por ejemplo,
su establecimiento a @code{#t} no tienen ningún efecto sobre las
ligaduras de expresión o de fraseo, o sobre otros extensores para los
que terminar en la barra de compás no tendría ningún significado.

@unnumberedsubsubsec Uso del @code{line-spanner-interface}

Entre los objetos que contemplan el interface
@code{line-spanner-interface} se encuentran

@itemize
@item @code{DynamicTextSpanner}
@item @code{Glissando}
@item @code{TextSpanner}
@item @code{TrillSpanner}
@item @code{VoiceFollower}
@end itemize

La rutina responsable de dibujar los sellos de estos extensores es
@code{ly:line-interface::print}.  esta rutina determina la
localización exacta de los dos puntos extremos y traza una línea entre
ellos, en el estilo solicitado.  Las posiciones de los dos puntos
extremos del extensor se calculan al vuelo, pero es posible
sobreescribir sus coordenadas Y.  Las propiedades que se deben
especificar están anidadas a dos niveles de profundidad en la
jerarquía de propiedades, pero la sintaxis de la instrucción
@code{\override} es bastante sencilla:

@lilypond[relative=2,quote,verbatim]
e2 \glissando b
\once \override Glissando #'(bound-details left Y) = #3
\once \override Glissando #'(bound-details right Y) = #-2
e2 \glissando b
@end lilypond

Las unidades para la propiedad @code{Y} son @code{staff-space}s,
siendo el punto del cero la línea central del pentagrama.  Para el
glissando, esto es el valor de @code{Y} en la coordenada X que
corresponde al punto central de cada cabeza de nota si nos imaginamos
que la línea se extiende hasta allí.

Si no está fijado @code{Y}, su valor se calcula a partir de la
posición vertical del punto de anclaje correspondiente del extensor.

En caso de salto de línea, los valores para los puntos extremos se
especifican por las sub-listas @code{left-broken} y
@code{right-broken} de @code{bound-details}.  Por ejemplo:

@lilypond[relative=2,ragged-right,verbatim,fragment]
\override Glissando #'breakable = ##t
\override Glissando #'(bound-details right-broken Y) = #-3
c1 \glissando \break
f1
@end lilypond

Un número de propiedades adicionales de las sub-listas @code{left} y
@code{right} de la propiedad @code{bound-details} se pueden
especificar de la misma forma que @code{Y}:

@table @code
@item Y
Establece la coordenada Y del punto extremo, en desplazamientos de
@code{staff-space}s desde la línea central del pentagrama.  De forma
predeterminada es el centro del objeto ancla, y así un glissando
apunta al centro vertical de la cabeza de la nota.

Para extensores horizontales como los extensores de texto y los
trinos, está inamoviblemente codificado como 0.

@item attach-dir (dirección de anclaje)
Determina dónde comienza y termina la línea en la dirección X, con
relación al objeto ancla.  Sí, un valor de @code{-1} (o @code{LEFT},
izquierda) hace que la línea comience o termine en el lado izquierdo
de la cabeza de la nota a la que está anclado.

@item X
Es la coordenada X absoluta del punto extremo.  Se suele calcular al
vuelo, y su sobreescritura no tiene un efecto útil.

@item stencil (sello)
Los extensores de línea pueden tener símbolos al comienzo o al final,
lo que está contenido en esta sub-propiedad.  Esto es para uso
interno; se recomienda en su lugar el uso de @code{text}.

@item text (texto)
Es un elemento de marcado que se evalúa para dar lugar al sello.  Se
usa para escribir @i{cresc.}, @i{tr} y otros textos sobre los objetos
de extensión horizontales.

@lilypond[quote,ragged-right,fragment,relative=2,verbatim]
\override TextSpanner #'(bound-details left text)
   = \markup { \small \bold Slower }
c2\startTextSpan b c a\stopTextSpan
@end lilypond

@item stencil-align-dir-y (alineación del sello en y)
@item stencil-offset (desplazamiento del sello)
Si no se modifican uno u otro, el sello se coloca sencillamente en el
punto extremo, centrado sobre la línea, como viene definido por las
subpropiedades @code{X} e @code{Y}.  Si se fijan
@code{stencil-align-dir-y} o @code{stencil-offset} se moverá el
símbolo del borde verticalmente con relación al extremo de la línea:

@lilypond[relative=1,fragment,verbatim]
\override TextSpanner
  #'(bound-details left stencil-align-dir-y) = #-2
\override TextSpanner
  #'(bound-details right stencil-align-dir-y) = #UP

\override TextSpanner
  #'(bound-details left text) = #"ggg"
\override TextSpanner
  #'(bound-details right text) = #"hhh"
c4^\startTextSpan c c c \stopTextSpan
@end lilypond

Observe que los valores negativos mueven el texto @emph{hacia arriba},
al contrario de lo que podría esperarse, pues el valor de @code{-1} o
@code{DOWN} (abajo) significa alinear el borde @emph{inferior} del
texto con la línea de extensión.  Un valor de @code{1} o @code{UP}
(arriba) alinea el borde superior del texto con la línea extensora.

@item arrow (flecha)
Al establecer esta sub-propiedad a @code{#t} se produce una punta de
flecha en el extremo de la línea.

@item padding (relleno)
Esta sub-propiedad controla el espacio entre el punto extremo
especificado de la línea y el extremo real.  Sin relleno, un glissando
empezaría y terminaría en el centro de la cabeza de las notas.

@end table

La función musical @code{\endSpanners} finaliza de forma prematura el
extensor que comienza sobre la nota que sigue inmediatamente a
continuación.  Se termina después de una nota exactamente, o en la
siguiente barra de compás si @code{to-barline} es verdadero y se
produce una divisoria antes de la siguiente nota.

@lilypond[verbatim,quote,ragged-right,relative=2,fragment]
\endSpanners
c2 \startTextSpan c2 c2
\endSpanners
c2 \< c2 c2
@end lilypond

Si se usa @code{\endSpanners} no es necesario cerrar \startTextSpan
con \stopTextSpan, ni cerrar los reguladores con @code{\!}.


@seealso
Referencia de funcionamiento interno:
@rinternals{TextSpanner},
@rinternals{Glissando},
@rinternals{VoiceFollower},
@rinternals{TrillSpanner},
@rinternals{line-spanner-interface}.


@node Visibilidad de los objetos
@subsection Visibilidad de los objetos
@translationof Visibility of objects

@cindex objetos, visibilidad de
@cindex grobs, visibilidad de
@cindex visibilidad de los objetos

Hay cuatro formas principales en que se puede controlar la visibilidad
de los objetos de presentación: se puede eliminar su sello, se pueden
volver transparentes, se pueden pintar de blanco, o se puede
sobreescribir su propiedad @code{break-visibility}.  Las tres primeras
se aplican a todos los objetos de presentación; la última sólo a unos
pocos: los objetos @emph{divisibles}.  El Manual de aprendizaje
introduce estas cuatro técnicas, véase @rlearning{Visibilidad y color de los objetos}.

Hay también algunas otras técnicas que son específicas de ciertos
objetos de presentación.  Se estudian bajo Consideraciones especiales.

@menu
* Eliminar el sello::
* Hacer transparentes los objetos::
* Pintar los objetos de blanco::
* Uso de break-visibility (visibilidad en el salto)::
* Consideraciones especiales::
@end menu


@node Eliminar el sello
@unnumberedsubsubsec Eliminar el sello
@translationof Removing the stencil

@cindex sello, eliminar

Todo objeto de presentación tiene una propiedad stencil (sello).  De
forma predeterminada está establecida a la función específica que
dibuja ese objeto.  Si se sobreescribe esta propiedad a @code{#f} no
se llama a ninguna función y el objeto no se dibuja.  La acción
predeterminada se puede recuperar con @code{\revert}.

@lilypond[quote,verbatim,relative=1]
a1 a
\override Score.BarLine #'stencil = ##f
a a
\revert Score.BarLine #'stencil
a a a
@end lilypond

@node Hacer transparentes los objetos
@unnumberedsubsubsec Hacer transparentes los objetos
@translationof Making objects transparent

@cindex transparentes, hacer los objetos

Todo objeto de presentación tiene una propiedad transparent
(transparente) que de forma predeterminada está establecida a
@code{#f}.  Si se fija a @code{#t} el objeto aún ocupa espacio pero es
invisible.

@lilypond[quote,verbatim,relative=2]
a4 a
\once \override NoteHead #'transparent = ##t
a a
@end lilypond

@node Pintar los objetos de blanco
@unnumberedsubsubsec Pintar los objetos de blanco
@translationof Painting objects white

@cindex objetos, coloreado de
@cindex coloreado de objetos
@cindex capas
@cindex impresión, orden de
@cindex sobreescritura de objetos
@cindex objetos, sobreescritura de
@cindex grobs, sobreescritura de

Todo objeto de presentación tiene una propiedad de color que de forma
predeterminada está establecida a @code{black} (negro).  Si se
sobreescribe a @code{white} (blanco) el objeto será indistinguible del
fondo blanco.  Sin embargo, si el objeto cruza a otros objetos, el
color de los puntos de cruce queda determinado por el orden en que se
dibujan estos objetos, lo que puede dejar una imagen fantasma del
objeto blanco, como puede verse aquí:

@lilypond[quote,verbatim,relative=2]
\override Staff.Clef #'color = #white
a1
@end lilypond

Se puede evitar esto cambiando el orden de impresión de los objetos.
Todos los objetos de presentación tienen una propiedad @code{layer}
(capa) que se debe establecer a un valor entero.  Los objetos con el
valor de @code{layer} más bajo se dibujan primero, después se dibujan
los objetos con valores progresivamente mayores, y así los objetos con
valores más altos se dibujan encima de los que tienen valores más
bajos.  De forma predeterminada, casi todos los objetos tienen
asignado un valor @code{layer} de @code{1}, aunque algunos objetos,
entre ellos el pentagrama y las líneas divisorias, @code{StaffSymbol}
y @code{BarLine}, tienen asignado un calor de @code{0}.  El orden de
impresión de los objetos con el mismo valor de @code{layer} es
indeterminado.

En el ejemplo de arriba, la clave blanca, con un valor @code{layer}
predeterminado de @code{1}, se dibuja después de las líneas del
pentagrama (valor @code{layer} predeterminado de @code{0}),
sobreimpresionándolas.  Para cambiarlo, se debe dar al objeto
@code{Clef} un valor de @code{layer} más bajo, digamos @code{-1}, para
que se dibuje antes:

@lilypond[quote,verbatim,relative=2]
\override Staff.Clef #'color = #white
\override Staff.Clef #'layer = #-1
a1
@end lilypond

@node Uso de break-visibility (visibilidad en el salto)
@unnumberedsubsubsec Uso de break-visibility (visibilidad en el salto)
@translationof Using break-visibility

@c TODO Add making other objects breakable

@cindex break-visibility

Casi todos los objetos de presentación se imprimen una sola vez, pero
algunos como las líneas divisorias, claves, indicaciones de compás y
armaduras de tonalidad, se pueden tener que imprimir dos veces cuando
se produce un salto de línea : una vez al final de la línea y otra al
comienzo de la siguiente.  Estos objetos reciben el nombre de
@emph{divisibles}, y tienen una propiedad, @code{break-visibility}
(visibilidad en el salto), para controlar su visibilidad en las tres
posiciones en que pueden aparecer: al comienzo de una línea, dentro de
la línea si se produce un cambio, y al final de la línea si el cambio
se produce en ese lugar.

Por ejemplo, la indicación de compás se imprime de forma
predeterminada al comienzo de la primera línea y en ningún otro lugar
a no ser que cambie, en cuyo caso se imprime en el punto en que se
produce el cambio.  Si este cambio se produce al final de una línea,
la nueva indicación de compás se imprime al principio de la línea
siguiente y también al final de la línea anterior como indicación de
precaución.

Este comportamiento se controla por medio de la propiedad
@code{break-visibility}, que se explica en
@c Leave this ref on a newline - formats incorrectly otherwise -td
@rlearning{Visibilidad y color de los objetos}.  Esta propiedad toma un
vector de tres valores booleanos que, por orden, determinan si el
objeto se imprime al final, dentro, o al principio de la línea.  O,
para ser más exactos: antes del salto de línea, si no hay salto, o
después del salto.

Como alternativa se puede especificar cualquiera de las ocho
combinaciones mediante funciones predefinidas cuya definición está en
@file{scm/output-lib.scm}, donde las tres últimas columnas indican si
los objetos de presentación serán visibles en las posiciones que se
muestran en el encabezamiento de cada columna:

@multitable {@code{begin-of-line-invisible}} {@code{'#(#t #t #t)}} {yes} {yes} {yes}
@headitem Forma                   @tab Forma                  @tab Antes del @tab Si no hay    @tab Después del
@headitem de función              @tab de vector              @tab salto     @tab salto        @tab salto

@item @code{all-visible}             @tab @code{'#(#t #t #t)}     @tab sí     @tab sí       @tab sí
@item @code{begin-of-line-visible}   @tab @code{'#(#f #f #t)}     @tab no     @tab no       @tab sí
@item @code{center-visible}          @tab @code{'#(#f #t #f)}     @tab no     @tab sí       @tab no
@item @code{end-of-line-visible}     @tab @code{'#(#t #f #f)}     @tab sí     @tab no       @tab no
@item @code{begin-of-line-invisible} @tab @code{'#(#t #t #f)}     @tab sí     @tab sí       @tab no
@item @code{center-invisible}        @tab @code{'#(#t #f #t)}     @tab sí     @tab no       @tab sí
@item @code{end-of-line-invisible}   @tab @code{'#(#f #t #t)}     @tab no     @tab sí       @tab sí
@item @code{all-invisible}           @tab @code{'#(#f #f #f)}     @tab no     @tab no       @tab no
@end multitable

Los ajustes predeterminados de @code{break-visibility} dependen del
objeto de presentación.  La tabla siguiente muestra todos los objetos
de presentación de interés que resultan afectados por
@code{break-visibility} y el ajuste predeterminado de esta propiedad:

@multitable @columnfractions .3 .3 .4

@headitem Objeto   @tab Contexto usual  @tab Valor predet.

@c omit Ambitus as it appears not to be affected by break-visibility -td
@c @item @code{Ambitus}          @tab as specified   @tab @code{begin-of-line-visible}
@item @code{BarLine}             @tab @code{Score}          @tab calculado
@item @code{BarNumber}           @tab @code{Score}          @tab @code{begin-of-line-visible}
@c omit the following item until it can be explained -td
@c @item @code{BreakAlignGroup}  @tab @code{Score}          @tab calculado
@item @code{BreathingSign}       @tab @code{Voice}          @tab @code{begin-of-line-invisible}
@item @code{Clef}                @tab @code{Staff}          @tab @code{begin-of-line-visible}
@item @code{Custos}              @tab @code{Staff}          @tab @code{end-of-line-visible}
@item @code{DoublePercentRepeat} @tab @code{Voice}          @tab @code{begin-of-line-invisible}
@c omit KeyCancellation until it can be explained -td
@c @item @code{KeyCancellation}  @tab ??             @tab @code{begin-of-line-invisible}
@item @code{KeySignature}        @tab @code{Staff}          @tab @code{begin-of-line-visible}
@c omit LeftEdge until it can be explained -td
@c @item @code{LeftEdge}         @tab @code{Score}          @tab @code{center-invisible}
@item @code{OctavateEight}       @tab @code{Staff}          @tab @code{begin-of-line-visible}
@item @code{RehearsalMark}       @tab @code{Score}          @tab @code{end-of-line-invisible}
@item @code{TimeSignature}       @tab @code{Staff}          @tab @code{all-visible}

@end multitable

El ejemplo de abajo muestra el uso de la forma de vector para
controlar la visibilidad de las líneas divisorias:

@lilypond[quote,verbatim,relative=1,ragged-right]
f4 g a b
f4 g a b
% Remove bar line at the end of the current line
\once \override Score.BarLine #'break-visibility = #'#(#f #t #t)
\break
f4 g a b
f4 g a b
@end lilypond

Aunque los tres componentes del vector utilizado para sobreescribir
@code{break-visibility} deben estar presentes, no todos son efectivos
para todos los objetos de presentación, y algunas combinaciones pueden
incluso dar errores.  Son de aplicación las siguientes limitaciones:

@itemize @bullet
@item Las líneas divisorias no se pueden imprimir al principio de la línea.
@item No se puede imprimir el número de compás al principio de la primera
línea a no ser que su valor establecido sea distinto de 1.
@item Clave: véase más abajo
@item Las repeticiones dobles de tipo porcentaje se imprimen completamente o
se suprimen por completo.  Utilice begin-of line-invisible para
imprimirlas y all-invisible para suprimirlas.
@item Armadura: véase más abajo
@item OctavateEight: véase más abajo
@end itemize

@node Consideraciones especiales
@unnumberedsubsubsec Consideraciones especiales
@translationof Special considerations

@strong{@emph{Visibilidad después de un cambio explícito}}

@cindex armadura, visibilidad después de un cambio explícito
@cindex explicitKeySignatureVisibility
@cindex clave, visibilidad después de un cambio explícito
@cindex explicitClefVisibility

La propiedad @code{break-visibility} controla la visibilidad de las
armaduras y cambios de clave sólo al principio de las líneas, es
decir, después de un salto.  No tiene ningún efecto sobre la
visibilidad de la armadura o la clave después de un cambio explícito
de tonalidad o de clave dentro o al final de una línea.  En el ejemplo
siguiente la armadura que sigue al cambio explícito de tonalidad a Si
bemol mayor es visible incluso con @code{all-invisible} establecido.

@lilypond[quote,verbatim,relative=1,ragged-right]
\key g \major
f4 g a b
% Try to remove all key signatures
\override Staff.KeySignature #'break-visibility = #all-invisible
\key bes \major
f4 g a b
\break
f4 g a b
f4 g a b
@end lilypond

La visibilidad de estos cambios explícitos de tonalidad y de clave se
controla por medio de las propiedades
@code{explicitKeySignatureVisibility} y @code{explicitClefVisibility}.
Son los equivalentes de la propiedad @code{break-visibility} y las dos
toman un vector de tres valores booleanos o las funciones predefinidas
relacionadas anteriormente, exactamente igual que
@code{break-visibility}.  Las dos son propiedades del contexto Staff,
no de los propios objetos de presentación, y por tanto se establecen
utilizando la instrucción @code{\set}.  Las dos están establecidas de
forma predeterminada al valor @code{all-visible}.  Estas propiedades
controlan sólo la visibilidad de las armaduras y las claves que
resultan de los cambios explícitos y no afectan a las armaduras y
tonalidades que están al principio de las líneas; para quitarlas, aún
se debe sobreescribir la propiedad @code{break-visibility} en el
objeto correspondiente.

@lilypond[quote,verbatim,relative=1,ragged-right]
\key g \major
f4 g a b
\set Staff.explicitKeySignatureVisibility = #all-invisible
\override Staff.KeySignature #'break-visibility = #all-invisible
\key bes \major
f4 g a b \break
f4 g a b
f4 g a b
@end lilypond

@strong{@emph{Visibilidad de las alteraciones de precaución}}

Para eliminar las alteraciones de precaución que se imprimen en un
cambio de tonalidad explícito, establezca la propiedad
@code{printKeyCancellation} del contexto Staff a @code{#f}:

@lilypond[quote,verbatim,relative=1,ragged-right]
\key g \major
f4 g a b
\set Staff.explicitKeySignatureVisibility = #all-invisible
\set Staff.printKeyCancellation = ##f
\override Staff.KeySignature #'break-visibility = #all-invisible
\key bes \major
f4 g a b \break
f4 g a b
f4 g a b
@end lilypond

Con estas sobreescrituras solamente permanecen las alteraciones
accidentales delante de las notas para indicar el cambio de tonalidad.

@c TODO Add visibility of cautionary accidentals before notes

@strong{@emph{Automatic bars}}

@cindex automaticBars
@cindex líneas divisorias, eliminación

Como caso especial, la impresión de las líneas divisorias también se
puede inhabilitar estableciendo la propiedad @code{automaticBars} en
el contexto Score.  Si se fija a @code{#f}, las barras de compás no se
imprimen automáticamente; se deben crear explícitamente con una
instrucción @code{\bar}.  A diferencia de la instrucción predefinida
@code{\cadenzaOn}, los compases se siguen contando.  La generación de
compases continúa de acuerdo a esta cuenta si esta propiedad se
establece posteriormente a @code{#t}.  Si se fija al valor @code{#f},
sólo pueden producirse saltos de línea en instrucciones @code{\bar}
explícitas.

@c TODO Add example

@strong{@emph{Octavated clefs}}

@cindex octavadas, visibilidad de las claves
@cindex visibilidad de las claves octavadas
@cindex claves, visibilidad de la octavación

El pequeño símbolo de octava sobre las claves en octava alta o baja se
produce por parte del objeto @code{OctavateEight}.  Su visibilidad se
controla independientemente de la del objeto @code{Clef}, así que es
necesario aplicar las sobreescrituras correspondientes
@code{break-visibility} tanto a los objetos @code{Clef} como
@code{OctavateEight} para suprimir completamente estos símbolos de
clave al comienzo de cada línea.

Para los cambios de clave explícitos, la propiedad
@code{explicitClefVisibility} controla tanto el símbolo de clave como
el símbolo de octava asociado.


@seealso
Manual de aprendizaje:
@rlearning{Visibilidad y color de los objetos}


@node Estilos de línea
@subsection Estilos de línea
@translationof Line styles

Ciertas indicaciones de ejecución, p.ej., @i{rallentando},
@i{accelerando} y los @i{trinos} se escriben como texto y se extienden
sobre muchos compases mediante líneas, a veces punteadas u onduladas.

Todos ellos usan las mismas rutinas que el glissando para dibujar los
textos y las líneas, y por ello el ajuste fino de su comportamiento se
hace de la misma manera. Se hace con un spanner (un objeto de
extensión), y la rutina responsable de dibujar los objetos de
extensión es @code{ly:line-interface::print}. Esta rutina determina la
colocación exacta de los dos @i{extremos del objeto de extensión} y
dibuja una línea entre ellos, en el estilo solicitado.

He aquí un ejemplo de los distintos estilos de línea disponibles, y
cómo aplicarles ajustes finos.

@lilypond[relative=2,ragged-right,verbatim,fragment]
d2 \glissando d'2
\once \override Glissando #'style = #'dashed-line
d,2 \glissando d'2
\override Glissando #'style = #'dotted-line
d,2 \glissando d'2
\override Glissando #'style = #'zigzag
d,2 \glissando d'2
\override Glissando #'style = #'trill
d,2 \glissando d'2
@end lilypond

Las posiciones de los puntos extremos del objeto de extensión se
computan al vuelo para cada uno de los objetos gráficos, pero es
posible sobreescribirlos:

@lilypond[relative=2,ragged-right,verbatim,fragment]
e2 \glissando f
\once \override Glissando #'(bound-details right Y) = #-2
e2 \glissando f
@end lilypond

El valor de @code{Y} está establecido a @code{-2} para el extremo
derecho.  El lado izquierdo se puede ajustar de forma similar
especificando @code{left} en vez de @code{right}.

Si no está establecido @code{Y}, el valor se computa a partir de la
posición vertical de los puntos de anclaje izquierdo y derecho del
extensor.

Son posibles otros ajustes de los extensores, para ver más detalles
consulte @ref{Objetos de extensión}.


@node Rotación de objetos
@subsection Rotación de objetos
@translationof Rotating objects

Tanto los objetos de presentación como los elementos de texto de
marcado se pueden girar cualquier ángulo respecto a cualquier punto,
pero difiere el método de hacerlo.

@menu
* Rotación de objetos de presentación::
* Rotación de elementos de marcado::
@end menu

@node Rotación de objetos de presentación
@unnumberedsubsubsec Rotación de objetos de presentación
@translationof Rotating layout objects

@cindex rotating objects
@cindex objects, rotating

Todos los objetos de presentación que contemplan el interface
@code{grob-interface} se pueden rotar estableciendo su propiedad
@code{rotation}.  Acepta una lista de tres elementos: el ángulo de la
rotación en sentido antihorario, y las coordenadas x e y del punto con
relación al punto de referencia del objeto, alrededor del que se va a
realizar la rotación.  El ángulo de rotación se especifica en grados
y las coordenadas en espacios de pentagrama.

El ángulo de rotación y las coordenadas del punto de rotación se deben
determinar por ensayo y error.

@cindex reguladores en ángulo
@cindex ángulo, reguladores en

Solamente en ciertas ocasiones es útil la rotación de objetos de
presentación; el ejemplo siguiente muestra una situación en que puede
serlo:

@lilypond[quote,verbatim,relative=1]
g4\< e' d' f\!
\override Hairpin #'rotation = #'(20 -1 0)
g,,4\< e' d' f\!
@end lilypond

@node Rotación de elementos de marcado
@unnumberedsubsubsec Rotación de elementos de marcado
@translationof Rotating markup

Todos los textos de marcado se pueden rotar para que se dispongan en
cualquier ángulo precediéndolos de la instrucción @code{\rotate}.  La
instrucción acepta dos argumentos: el ángulo de rotación en grados en
sentido antihorario, y el texto que rotar.  Los límites que ocupa el
texto no se rotan: toman su valor a partir de los extremos de las
coordenadas x e y del texto rotado.  En el ejemplo siguiente la
propiedad @code{outside-staff-priority} del texto se establece a
@code{#f} para desactivar la evitación automática de colisiones, lo
que empuja al texto a una posición muy alta.

@lilypond[quote,verbatim,relative=1]
\override TextScript #'outside-staff-priority = ##f
g4^\markup { \rotate #30 "a G" }
b^\markup { \rotate #30 "a B" }
des^\markup { \rotate #30 "a D-Flat" }
fis^\markup { \rotate #30 "an F-Sharp" }
@end lilypond

@node Trucos avanzados
@section Trucos avanzados
@translationof Advanced tweaks

Esta sección trata sobre distintos enfoques en la realización de
ajustes finos a la apariencia de la partitura impresa.

@menu
* Alineación de objetos::
* Agrupación vertical de objetos gráficos::
* Modificación de los sellos::
* Modificación de las formas::
@end menu


@seealso
Manual de aprendizaje:
@rlearning{Trucar la salida},
@rlearning{Otras fuentes de información}.

Referencia de la notación:
@ref{Explicación del Manual de referencia de funcionamiento interno},
@ref{Modificar las propiedades}.


Archivos de inicio:
@file{scm/@/define@/-grobs@/.scm}.

Fragmentos de código:
@rlsr{Tweaks and overrides}.

Extender:
@rextend{Interfaces for programmers}.

Referencia de funcionamiento interno:
@rinternals{All layout objects}.


@node Alineación de objetos
@subsection Alineación de objetos
@translationof Aligning objects

Los objetos gráficos que soportan el interface
@code{self-alignment-interface} y/o el @code{side-position-interface}
se pueden alinear contra un objeto colocado previamente, de diversas
maneras.  Para ver una lista de estos objetos, consulte
@rinternals{self-alignment-interface} y
@rinternals{side-position-interface}.

Todos los objetos gráficos tienen un punto de referencia, una
extensión horizontal y una extensión vertical.  La extensión
horizontal es una pareja de números que dan los desplazamientos a
partir del punto de referencia de los bordes izquierdo y derecho,
siendo negativos los desplazamientos hacia la izquierda.  La extensión
vertical es una pareja de números que dan el desplazamiento a partir
del punto de referencia hasta los bordes inferior y superior, siendo
negativos los desplazamientos hacia abajo.

La posición de un objeto sobre el pentagrama viene dada por los
valores de las propiedades @code{X-offset} e @code{Y-offset}.  El
valor de @code{X-offset} da el desplazamiento desde la coordenada x
del punto de referencia del objeto padre, y el valor de
@code{Y-offset} da el desplazamiento a partir de la línea central del
pentagrama.  Los valores de @code{X-offset} y @code{Y-offset} se
pueden establecer directamente o se puede dejar que se calculen por
parte de procedimientos para conseguir una alineación con el objeto
padre de distintas maneras.

@warning{Muchos objetos tienen consideraciones de posicionamiento
especiales que hacen que se ignore o se modifique cualquier ajuste
realizado a @code{X-offset} o a @code{Y-offset}, a pesar de que el
objeto contemple el interface @code{self-alignment-interface}.}

Por ejemplo, una alteración accidental se puede reposicionar
verticalmente estableciendo @code{Y-offset} pero los cambios a
@code{X-offset} no tienen ningún efecto.

Las letras de ensayo se pueden alinear con objetos divisibles como
líneas divisorias, claves, armaduras e indicaciones de compás.  Hay
propiedades especiales que se encuentran en
@code{break-aligned-interface} para el posicionamiento de las letras
de ensayo sobre dichos objetos.

@menu
* Establecer directamente @code{X-offset} y @code{Y-offset}::
* Uso del @code{side-position-interface}::
* Uso del @code{self-alignment-interface}::
* Uso del @code{break-alignable-interface}::
@end menu

@node Establecer directamente @code{X-offset} y @code{Y-offset}
@unnumberedsubsubsec Establecer directamente @code{X-offset} y @code{Y-offset}
@translationof Setting @code{X-offset} and @code{Y-offset} directly

Se pueden dar valores numéricos a las propiedades @code{X-offset} y
@code{Y-offset} de muchos objetos.  El ejemplo siguiente muestra tres
notas con una digitación en su posición predeterminada y con los
valores @code{X-offset} y @code{Y-offset} modificados.

@lilypond[verbatim,quote,relative=2]
a-3
a
-\tweak #'X-offset #0
-\tweak #'Y-offset #0
-3
a
-\tweak #'X-offset #-1
-\tweak #'Y-offset #1
-3
@end lilypond

@c TODO write more

@node Uso del @code{side-position-interface}
@unnumberedsubsubsec Uso del @code{side-position-interface}
@translationof Using the @code{side-position-interface}

Un objeto que contempla el @code{side-position-interface} se puede
colocar junto a su objeto padre de forma que los bordes especificados
de los dos objetos se toquen.  El objeto se puede situar encima,
debajo, a la derecha o a la izquierda del objeto padre.  El padre no
se puede especificar; viene determinado por el orden de los elementos
en el flujo de entrada.  Casi todos los objetos tienen la cabeza de la
nota asociada como padre.

Los valores de las propiedades @code{side-axis} y @code{direction}
determinan dónde colocar el objeto, como sigue:

@c TODO add an example of each to the table

@multitable @columnfractions .3 .3 .3
@headitem @code{side-axis}  @tab @code{direction}  @tab
@headitem propiedad         @tab propiedad         @tab colocación

@item     @code{0}          @tab @code{-1}         @tab izquierda
@item     @code{0}          @tab @code{1}          @tab derecha
@item     @code{1}          @tab @code{-1}         @tab debajo
@item     @code{1}          @tab @code{1}          @tab encima

@end multitable

Si @code{side-axis} es @code{0}, @code{X-offset} se debe establecer al
procedimiento @code{ly:side-position-interface::x-aligned-side}.  Este
procedimiento devuelve el calor correcto de @code{X-offset} para
situar el objeto al lado izquierdo o derecho del padre de acuerdo con
el valor de @code{direction}.

Si @code{side-axis} es @code{1}, @code{Y-offset} se debe establecer al
procedimiento @code{ly:side-position-interface::y-aligned-side}.  Este
procedimiento devuelve el valor correcto de @code{Y-offset} para
situar el objeto encima o debajo del padre de acuerdo con el valor de
@code{direction}.

@c TODO Add examples

@node Uso del @code{self-alignment-interface}
@unnumberedsubsubsec Uso del @code{self-alignment-interface}
@translationof Using the @code{self-alignment-interface}

@emph{Auto-alineación horizontal de los objetos}

La alineación horizontal de un objeto que contempla el interface
@code{self-alignment-interface} está controlada por el valor de la
propiedad @code{self-alignment-X}, siempre y cuando la propiedad
@code{X-offset} de este objeto esté establecida a
@code{ly:self-alignment-interface::x-aligned-on-self}.  Se le puede
dar a @code{self-alignment-X} cualquier valor real, en unidades de la
mitad de la extensión X total del objeto.  Los valores negativos
mueven el objeto a la derecha, los positivos hacia la izquierda.  Un
valor de @code{0} centra el objeto sobre el punto de referencia de su
padre, un valor de @code{-1} alinea el borde izquierdo del objeto
sobre el punto de referencia de su padre, y un valor de @code{1}
alinea el borde derecho del objeto sobre el punto de referencia de su
padre.  Se pueden usar los símbolos @code{LEFT}, @code{CENTER} y
@code{RIGHT} en sustitución de los valores @code{-1, 0, 1},
respectivamente.

Normalmente se usaría la instrucción @code{\override} para modificar
el valor de @code{self-alignment-X}, pero se puede usar la instrucción
@code{\tweak} para alinear varias anotaciones por separado sobre una
sola nota:

@lilypond[quote,verbatim,relative=1]
a'
-\tweak #'self-alignment-X #-1
^"left-aligned"
-\tweak #'self-alignment-X #0
^"center-aligned"
-\tweak #'self-alignment-X #RIGHT
^"right-aligned"
-\tweak #'self-alignment-X #-2.5
^"aligned further to the right"
@end lilypond

@emph{Auto-alineación vertical de los objetos}

Los objetos se pueden alinear verticalmente en una forma análoga a la
alineación horizontal si la propiedad @code{Y-offset} está establecida
a @code{ly:self-alignment-interface::y-aligned-on-self}.  Sin embargo,
a menudo se encuentran implicados otros mecanismos en la alineación
vertical: el valor de @code{Y-offset} es tan sólo una variable que se
tiene en cuenta.  Esto puede hacer que ajustar el valor de ciertos
objetos sea una tarea dificultosa.  Las unidades son sólo la mitad de
las dimensiones verticales del objeto, que suele ser bastante pequeño,
por lo que pueden requerirse números bastante grandes.  Un valor de
@code{-1} alinea el borde inferior del objeto con el punto de
referencia del objeto padre, un valor de @code{0} alinea el centro del
objeto con el punto de referencia del padre, y un valor de @code{1}
alinea el borde superior del objeto con el punto de referencia del
padre.  Se pueden usar los símbolos @code{DOWN}, @code{CENTER},
@code{UP} en sustitución de @code{-1, 0, 1} respectivamente.

@emph{Auto-alineación de objetos en las dos direcciones}

Estableciendo tanto @code{X-offset} como @code{Y-offset}, se puede
alinear un objeto en las dos direcciones simultáneamente.

El ejemplo siguiente muestra cómo ajustar una digitación de forma que
se acerque a la cabeza de la nota.

@lilypond[quote,verbatim,relative=2]
a
-\tweak #'self-alignment-X #0.5  % move horizontally left
-\tweak #'Y-offset #ly:self-alignment-interface::y-aligned-on-self
-\tweak #'self-alignment-Y #-1  % move vertically up
-3  % third finger
@end lilypond

@ignore
@unnumberedsubsubsec Uso de los procedimientos @code{aligned-on-parent}

@c Cannot document as they do not seem to operate consistently on all objects -td
@c TODO investigate further

The @code{aligned-on-parent} procedures are used in the same way
as the @code{aligned-on-self} procedures, they difference being
that they permit an object to be aligned with the @emph{edges} of
the parent rather than the parent's reference point.  The following
example shows the difference:

@c TODO Add example

@lilypond[verbatim,quote]
@end lilypond

@end ignore

@ignore
@unnumberedsubsubsec Uso de los procedimientos @code{centered-on-parent}

@c Cannot document as they do not seem to operate consistently on all objects -td
@c TODO investigate further

@end ignore

@c TODO The align-interface, BassFigureAlignment and VerticalAlignment


@node Uso del @code{break-alignable-interface}
@unnumberedsubsubsec Uso del @code{break-alignable-interface}
@translationof Using the @code{break-alignable-interface}

@cindex alineación a objetos
@cindex break-align-symbols

Las letras de ensayo se pueden alinear con objetos de notación
distintos a las barras de compás.  Estos objetos son @code{ambitus},
@code{breathing-sign}, @code{clef}, @code{custos}, @code{staff-bar},
@code{left-edge}, @code{key-cancellation}, @code{key-signature} y
@code{time-signature}.

De forma predeterminada, las letras de ensayo y los números de compás
se centran horizontalmente sobre el objeto:

@lilypond[verbatim,quote,relative=1]
e1
% the RehearsalMark will be centered above the Clef
\override Score.RehearsalMark #'break-align-symbols = #'(clef)
\key a \major
\clef treble
\mark "↓"
e
% the RehearsalMark will be centered above the TimeSignature
\override Score.RehearsalMark #'break-align-symbols = #'(time-signature)
\key a \major
\clef treble
\time 3/4
\mark "↓"
e2.
@end lilypond

Se puede especificar una lista de posibles objetos para la alineación.
Si algunos de los objetos son invisibles en ese punto debido al valor
de @code{break-visibility} o a valores de visibilidad explícitos para
las armaduras y las claves, la letra de ensayo o número de compás se
alinean con el primer objeto de la lista que sea visible.  Si ningún
objeto de la lista es visible, el objeto se alinea con la línea
divisoria.  Si la línea divisoria es invisible, el objeto se alinea
con el punto en el que se encontraría la línea divisoria.

@lilypond[verbatim,quote,relative=1]
e1
% the RehearsalMark will be centered above the Key Signature
\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
\key a \major
\clef treble
\mark "↓"
e
% the RehearsalMark will be centered above the Clef
\set Staff.explicitKeySignatureVisibility = #all-invisible
\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
\key a \minor
\clef bass
\mark "↓"
e,
@end lilypond

La alineación de la letra de ensayo con relación al objeto de notación
se puede cambiar, como se ve en el ejemplo siguiente.  En una
partitura con varios pentagramas, este ajuste se debe hacer para todos
los pentagramas.

@lilypond[verbatim,quote,relative=1]
% The RehearsalMark will be centered above the KeySignature
\override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
\key a \major
\clef treble
\time 4/4
\mark "↓"
e1
% The RehearsalMark will be aligned with the left edge of the KeySignature
\once \override Score.KeySignature #'break-align-anchor-alignment = #LEFT
\mark "↓"
\key a \major
e
% The RehearsalMark will be aligned with the right edge of the KeySignature
\once \override Score.KeySignature #'break-align-anchor-alignment = #RIGHT
\key a \major
\mark "↓"
e
@end lilypond

La letra de ensayo también se puede desplazar al borde derecho o
izquierdo en una medida arbitraria.  Las unidades son espacios de
pentagrama:

@lilypond[verbatim,quote,relative=1]
% The RehearsalMark will be aligned with the left edge of the KeySignature
% and then shifted right by 3.5 staff-spaces
\override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
\once \override Score.KeySignature #'break-align-anchor = #3.5
\key a \major
\mark "↓"
e
% The RehearsalMark will be aligned with the left edge of the KeySignature
% and then shifted left by 2 staff-spaces
\once \override Score.KeySignature #'break-align-anchor = #-2
\key a \major
\mark "↓"
e
@end lilypond


@node Agrupación vertical de objetos gráficos
@subsection Agrupación vertical de objetos gráficos
@translationof Vertical grouping of grobs

Los grobs (objetos gráficos) @code{VerticalAlignment} y
@code{VerticalAxisGroup} trabajan de manera coordinada.
@code{VerticalAxisGroup} agrupa distintos grobs como @code{Staff},
@code{Lyrics}, etc.  Después, @code{VerticalAlignment} alinea los
distintos grobs agrupados previamente por @code{VerticalAxisGroup}.
Normalmente sólo existe un @code{VerticalAlignment} por cada
partitura, pero cada @code{Staff}, @code{Lyrics}, etc. tiene su propio
@code{VerticalAxisGroup}.


@node Modificación de los sellos
@subsection Modificación de los sellos
@translationof Modifying stencils

Todos los objetos de presentación tienen una propiedad @code{stencil}
que es parte del @code{grob-interface}.  De forma predeterminada, esta
propiedad suele estar establecida a una función específica del objeto
que está hecha a medida para disponer el símbolo que lo representa en
la salida.  Por ejemplo, el ajuste estándar para la propiedad
@code{stencil} del objeto @code{MultiMeasureRest} es
@code{ly:multi-measure-rest::print}.

El símbolo estándar de cualquier objeto se puede sustituir modificando
la propiedad @code{stencil} para que haga referencia a un
procedimiento diferente escrito especialmente.  Esto requiere un alto
nivel de conocimiento del funcionamiento interno de LilyPond, pero hay
una forma más fácil que a menudo puede dar resultados adecuados.

El procedimiento es establecer la propiedad @code{stencil} al
procedimiento que imprime texto (@code{ly:text-interface::print}) y
añadir una propiedad @code{text} al objeto ajustada para que contenga
el texto de marcado que produce el símbolo requerido.  Debido a la
flexibilidad del marcado, se pueden conseguir muchas cosas; en
particular, consulte @ref{Notación gráfica dentro de elementos de marcado}.

El ejemplo siguiente muestra esto cambiando el símbolo de la cabeza de
la nota a unas aspas dentro de una circunferencia.

@lilypond[verbatim,quote]
XinO = {
  \once \override NoteHead  #'stencil = #ly:text-interface::print
  \once \override NoteHead #'text = \markup {
    \combine
      \halign #-0.7 \draw-circle #0.85 #0.2 ##f
      \musicglyph #"noteheads.s2cross"
  }
}
\relative c'' {
  a a \XinO a a
}
@end lilypond

Cualquiera de los glifos de la fuente tipográfica Feta se puede pasar
a la instrucción de marcado @code{\musicglyph}: véase @ref{La tipografía Feta}.

@c TODO Add inserting eps files or ref to later

@c TODO Add inserting Postscript or ref to later


@seealso
Referencia de la notación:
@ref{Notación gráfica dentro de elementos de marcado},
@ref{Formatear el texto},
@ref{Text markup commands},
@ref{La tipografía Feta}.


@node Modificación de las formas
@subsection Modificación de las formas
@translationof Modifying shapes

@menu
* Modificación de ligaduras de unión y de expresión::
@end menu

@node Modificación de ligaduras de unión y de expresión
@unnumberedsubsubsec Modificación de ligaduras de unión y de expresión
@translationof Modifying ties and slurs

@cindex ligaduras de expresión, modificar
@cindex ligaduras de unión, modificar
@cindex Bézier, curvas de
@cindex Bézier, puntos de control

Las ligaduras de unión, de expresión y de fraseo se trazan como curvas
de Bézier de tercer orden.  Si la forma de la ligadura calculada
automáticamente no resulta óptima, se puede modificar su forma
manualmente mediante la especificación explícita de los cuatro puntos
de control necesarios para definir una curva de Bézier de tercer
orden.

Las curvas Bézier de tercer orden o cúbicas están definidas por cuatro
puntos de control.  El primer y cuarto puntos de control son
exactamente los puntos extremos de comienzo y de final de la curva.
Los dos puntos de control intermedios definen la forma.  Se pueden
encontrar en la web animaciones que muestran cómo se traza la curva,
pero la descripción siguiente puede ser de ayuda.  La curva comienza a
partir del primer punto de control dirigiéndose directamente hacia el
segundo, curvándose progresivamente para dirigirse hacia el tercero y
continuando la curva hacia el cuarto, llegando a éste en viaje directo
desde el tercer punto de control.  La curva está contenida enteramente
dentro del cuadrilátero definido por los cuatro puntos de control.

He aquí un ejemplo de un caso en que la ligadura no es óptima, y donde
@code{\tieDown} no sirve de ayuda.

@lilypond[verbatim,quote,relative=1]
<<
  { e1 ~ e }
\\
  { r4 <g c,> <g c,> <g c,> }
>>
@end lilypond

Una forma de mejorar esta ligadura es modificar manualmente sus puntos
de control como sigue.

Las coordenadas de los puntos de control de Bézier se especifican en
unidades de espacios de pentagrama.  La coordenada@tie{}X está en
relación con el punto de referencia de la nota a la que está unida la
ligadura, y la coordenada@tie{}Y está en relación con la línea central
del pentagrama.  Las coordenadas se introducen como una lista de
cuatro parejas de números decimales (reales).  Un enfoque es estimar
las coordenadas de los dos puntos extremos, y luego tratar de adivinar
los dos puntos intermedios.  Los valores óptimos se encuentran por
ensayo y error.

Es útil recordar que una curva simétrica necesita puntos de control
simétricos, y que las curvas de Bézier tienen la útil propiedad de que
las transformaciones de la curva tales como la traslación, rotación y
escalado se pueden obtener aplicando la misma transformación a los
puntos de control de la curva.

Para el ejemplo anterior, la sobreescritura siguiente da una ligadura
satisfactoria.  Observe la colocación: debe ir inmediatamente antes de
la nota a la que se asigna el comienzo de la ligadura de expresión o
de unión.

@lilypond[verbatim,quote,relative=1]
<<
  {
    \once \override Tie
      #'control-points = #'((1 . -1) (3 . 0.6) (12.5 . 0.6) (14.5 . -1))
     e1 ~ e1
  }
\\
  { r4 <g c,> <g c,> <g c,>4  }
>>
@end lilypond

@knownissues

No es posible modificar la forma de las ligaduras de unión o de
expresión cambiando la propiedad @code{control-points} si hay más de
una en el mismo momento musical, ni siquiera usando la instrucción
@code{\tweak}.



@node Uso de las funciones musicales
@section Uso de las funciones musicales
@translationof Using music functions

@c TODO -- add @seealso, etc. to these subsections

Dondequiera que se necesite reutilizar trucos con distintas
expresiones musicales, con frecuencia conviene hacer que el truco
forme parte de una función musical.  En esta sección estudiaremos
solamente las funciones de @emph{sustitución}, en las que el objeto es
sustituir una variable dentro de un fragmento de código de entrada de
LilyPond.  Se describen otras funciones más complejas en
@rextend{Music functions}.

@menu
* Sintaxis de las funciones de sustitución::
* Tipos de argumento comunes::
* Ejemplos de funciones de sustitución::
@end menu

@node Sintaxis de las funciones de sustitución
@subsection Sintaxis de las funciones de sustitución
@translationof Substitution function syntax

Es fácil hacer una función que sustituya una variable dentro de código
de LilyPond.  La forma general de estas funciones es

@example
funcion =
#(define-music-function (parser location @var{var1} @var{var2}...@var{vari}... )
                        (@var{tipo-de-var1?} @var{tipo-de-var2?}...@var{tipo-de-vari?}...)
  #@{
    @emph{...música...}
  #@})
@end example

@noindent
donde

@multitable @columnfractions .33 .66
@item @var{vari}         @tab @var{i}-ésima variable
@item @var{tipo-de-vari?}   @tab tipo de la variable  @var{i}-ésima
@item @var{...música...}  @tab entrada de LilyPond normal, que utiliza variables como @code{#$var1}, etc.
@end multitable

Los tipos de variable comunes se describen en @ref{Tipos de argumento
comunes}.  Hay una descripción más completa de los tipos de variable
en @rextend{Music function syntax}.  La lista completa de los tipos de
variable definidos está en el elemento @var{type-p-name-alist} de
@file{scm/lily.scm}.

@c TODO -- find an automatic way of documenting the type-p-name-alist


Los argumentos @code{parser} y @code{location} son necesarios, y se
utilizan en algunas situaciones avanzadas como se encuentra descrito
en @rextend{Music function syntax}.  Para las funciones de
sustitución, tan sólo hemos de asegurarnos de incluirlos.

@seealso

Referencia de la notación:
@ref{Tipos de argumento comunes}.

Expansión de LilyPond:
@rextend{Music function syntax}.

@node Tipos de argumento comunes
@subsection Tipos de argumento comunes
@translationof Common argument types

Para hacer posible la comprobación de errores, se debe definir el tipo
de cada argumento que se pasa a una función musical.  Algunos de los
tipos de variable comunes están relacionados en la tabla que aparece
más abajo.

Los siguientes tipos de entrada se pueden utilizar como variables
dentro de una función musical.  La lista no es exhaustiva; hay más
información sobre los posibles tipos de variable en
@rextendnamed{Music function syntax,Sintaxis de las funciones
musicales}.

@multitable @columnfractions .33 .66
@headitem Tipo de entrada       @tab notación de @var{tipo-de-vari?}
@item Entero                    @tab @code{integer?}
@item Flotante (número decimal) @tab @code{number?}
@item Cadena de caracteres      @tab @code{string?}
@item Marcado                   @tab @code{markup?}
@item Expresión musical         @tab @code{ly:music?}
@item Dupla de Scheme           @tab @code{pair?}
@end multitable

@seealso

Expansión de LilyPond:
@rextend {Music function syntax}.

Archivos instalados:
@file{lily/music-scheme.cc},
@file{scm/c++.scm}.


@node Ejemplos de funciones de sustitución
@subsection Ejemplos de funciones de sustitución
@translationof Substitution function examples

Esta sección presenta algunos ejemplos de funciones de sustitución.
No pretenden ser exhaustivas, sino demostrar algunas de las
posibilidades de las funciones de sustitución sencillas.

En el primer ejemplo se define una función que simplifica el ajuste
del relleno de un elemento de inscripción de texto TextScript:

@lilypond[quote,verbatim,ragged-right]
padText = #(define-music-function (parser location padding) (number?)
  #{
    \once \override TextScript #'padding = #$padding
  #})

\relative c''' {
  c4^"piu mosso" b a b
  \padText #1.8
  c4^"piu mosso" d e f
  \padText #2.6
  c4^"piu mosso" fis a g
}
@end lilypond

Además de números, podemos usar expresiones musicales, como notas,
para los argumentos de las funciones musicales:

@lilypond[quote,verbatim,ragged-right]
custosNote = #(define-music-function (parser location note)
                                     (ly:music?)
  #{
    \once \override Voice.NoteHead #'stencil =
      #ly:text-interface::print
    \once \override Voice.NoteHead #'text =
      \markup \musicglyph #"custodes.mensural.u0"
    \once \override Voice.Stem #'stencil = ##f
    $note
  #})

{ c' d' e' f' \custosNote g' }
@end lilypond

Se pueden definir funciones de sustitución con varios argumentos:

@lilypond[quote,verbatim,ragged-right]
tempoPadded = #(define-music-function (parser location padding tempotext)
  (number? string?)
#{
  \once \override Score.MetronomeMark #'padding = $padding
  \tempo \markup { \bold $tempotext }
#})

\relative c'' {
  \tempo \markup { "Low tempo" }
  c4 d e f g1
  \tempoPadded #4.0 #"High tempo"
  g4 f e d c1
}
@end lilypond

@c @seealso