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

@ignore
Translation of GIT committish: e14f3b2735ee559b06211f1b9a082923705f0970

    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.25.24"


@part Cambiar los valores por omisión

@node Tuning output
@anchor{Changing defaults} @c retain old label
@chapter Ajuste fino de la salida

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

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
@dfn{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 @rlearningnamed{Tweaking output, 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
@rinternals{Top}.  Dicho
manual relaciona todas las variables, funciones y opciones que se
encuentran disponibles en 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 inician dentro de un archivo @file{.ly} con
el símbolo de
cuadradillo@tie{}@samp{#}.@footnote{@rextendnamed{Scheme tutorial,
Tutorial de Scheme} contiene un breve tutorial sobre la
introducción de números, listas, cadenas y símbolos en Scheme.}


@node Interpretation contexts
@chapter Contextos de interpretación

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

@morerefs
Manual de aprendizaje:
@rlearningnamed{Contexts and engravers, Contextos y grabadores}.

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

Fragmentos de código:
@rlsrnamed{Contexts and engravers,Contextos y grabadores}.

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


@node Contexts explained
@section Explicación de los contextos

Los contextos se disponen de forma jerárquica.


@node Output definitions - blueprints for contexts
@subsection Definiciones de salida - estructura de los contextos

Esta sección explica la relevancia de las definiciones de salida
cuando se trabaja con los @dfn{contextos}. Más adelante ofrecemos
ejemplos de definiciones de salida reales (@pxref{Changing all
contexts of the same type}).

@cindex salida, definiciones de
@funindex \layout
Aunque la música escrita en un archivo haga referencia a tipos y
nombres de contexto, los contextos se crean solamente cuando la
música se está realmente interpretando.  LilyPond interpreta la
música bajo el control de una @dfn{definición de salida} y puede
hacerlo así para varias definiciones de salida distintas, dando
como resultado distintas salidas también.  La definicion de salida
que corresponde a la impresión de la música se especifica mediante
@code{\layout}.

@funindex \midi
Una definición de salida mucho más sencilla que se usa para la
producción de MIDI se especifica mediante @code{\midi}.
Internamente, LilyPond utiliza varias otras definiciones de
salida, como cuando se usa el combinador de particellas
(@ref{Automatic part combining}) o se crean fragmentos
de notas guía citadas (@ref{Quoting other voices}).

Las definiciones de salida establecen la relación entre los
contextos así como sus respectivos valores predeterminados.
Aunque la mayor parte de los cambios se suelen hacer dentro de un
bloque @code{\layout}, los ajustes de valores relacionados con el
MIDI solamente tienen efecto cuando se hacen dentro de un bloque
@code{\midi} block.

@funindex autoBeaming
Algunos ajustes afectan a varias salidas: por ejemplo, si se
desactiva el barrado automático, @code{autoBeaming}, dentro de
algún contexto, las barras cuentan como melismas en lo que
respecta a la correspondencia entre la música y la letra,
@pxref{Automatic syllable durations}.  Esta correspondencia se
hace tanto para la salida impresa como para el MIDI.  Si los
cambios hechos sobre el @code{autoBeaming} dentro de la definición
de contexto de un bloque @code{\layout} no se repiten dentro del
correspondiente bloque @code{\midi}, la letra y la música dejarán
de estar sincronizadas dentro del MIDI.

@morerefs
Archivos instalados:
@file{ly/engraver-init.ly}.
@file{ly/performer-init.ly}.
@endmorerefs

@node Score - the master of all contexts
@subsection @code{Score}: el contexto maestro

@funindex Score
@funindex Global
Este es el contexto de notación del nivel más alto que
hay.@footnote{Existe un contexto llamado @code{Global} que está
incluso a un nivel más alto que @code{Score}, y que es el punto de
entrada fijo programado para LilyPond.  Sin embargo, se supone que
este contexto nunca se modifica; es necesario solamente si vamos a
implementar un grabador en Scheme y en caso contrario se puede
simplemente ignorar.}  Ningún otro contexto puede contener a un
contexto @code{Score}.  Este contexto se encarga de gestionar las
indicaciones de compás.  También garantiza que elementos como las
claves, el compás y las armaduras de tonalidad están alineados
entre los distintos pentagramas.

No podemos instanciar un contexto @code{Score} explícitamente (ya
que no está contenido dentro de ningún otro contexto).  Se crea
una instancia automáticamente cuando se procesa una definición de
salida (un bloque @code{\score} o @code{\layout}).

@funindex Timing
Se establece por parte de @code{Timing_translator} un alias
llamado @code{Timing} dentro de cualquier contexto en que se
inicializa, y las variables de la cuenta de tiempo se copian a
partir del lugar en que se haya establecido @code{Timing}
previamente.  El alias en el nivel de @code{Score} ofrece una
diana para inicializar las variables de @code{Timing} dentro de
las definiciones de presentación antes de que se haya ejecutado
cualquier @code{Timing_translator}.


@node Top-level contexts - staff containers
@subsection Contextos del nivel superior: contenedores de pentagramas

@table @code
@item StaffGroup (grupo de pentagramas)
@funindex StaffGroup
Agrupa pentagramas y añade un corchete en la parte izquierda,
formando un grupo.  Además, las líneas divisorias de los
pentagramas contenidos se conectan verticalmente.

@item ChoirStaff (sistema de coro)
@funindex ChoirStaff
Idéntico a @code{StaffGroup} excepto que las barras de compás de
los pentagramas contenidos no se conectan verticalmente.

@item GrandStaff (sistema de piano)
@funindex GrandStaff
Conectar las pautas verticalmente mediante una llave en el lado
izquierdo.  Las barras de compás de las pautas contenidas también
se conectan verticalmente.

@item PianoStaff (sistema de piano)
@funindex PianoStaff
Igual que @code{GrandStaff}, pero los pentagramas se eliminan
siempre juntos, nunca por separado.

@item OneStaff (una pauta)
@funindex OneStaff
@funindex \startStaff
@funindex \stopStaff
Ofrece un eje común para las pautas contenidas, haciendo que
aparezcan dentro del mismo espacio vertical.  Esto puede ser útil
para tipografiar pautas de distinto tipo sucesivamente, o para
cambiar temporalmente el carácter de una pauta, o para
superponerle otra distinta.  Los mejores resultados se obtienen
frecuentemente cuando se usa con @code{\stopStaff} y
@code{\startStaff}.

@item VaticanaScore (partitura de Vaticana)
@funindex VaticanaScore
Contexto del nivel superior que suple a @code{Score} para canto
gregoriano en el estilo de la edición vaticana.  Comparado con
@code{Score}, cambia el color de las líneas de la pauta a rojo,
usa un espaciado compacto y suprime los números de compás.

@item ChordGridScore (rejilla de acordes)
@funindex ChordGridScore
Contexto del nivel superior que suple a @code{Score} en notación
de rejilla de acordes.  Comparado con @code{Score}, usa notación
proporcional, y tiene otros ajustes como la eliminación de los
números de compás, por ejemplo.

@item StandaloneRhythmScore (partitura rítimica autocontenida)
@funindex StandaloneRhythmScore
@funindex \rhythm
Un contexto del mismo nivel que @code{Score} para su uso por parte
de @code{\markup \rhythm}.
@end table


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

@table @code
@item Staff (pauta o pentagrama)
@funindex Staff
Maneja claves, barras de compás, tonalidades y alteraciones
accidentales.  Puede contener contextos de @code{Voice}.

@item RhythmicStaff (pauta rítmica)
@funindex RhythmicStaff
Como @code{Staff}, pero para imprimir ritmos.  Al imprimir se
ignoran las alturas de las notas; las notas se imprimen sobre una
línea.  La salida de MIDI conserva las alturas sin modificación.

@item TabStaff (pauta de tablatura)
@funindex TabStaff 
Contexto para generar tablaturas.  Solo acepta contextos
@code{TabVoice} y maneja adecuadamente el espaciado de líneas, la
clave de tablatura, etc.

@item DrumStaff (pauta de percusión)
@funindex DrumStaff
Maneja el tipografiado para instrumentos de percusión.  Puede contener
contextos @code{DrumVoice}.

@item VaticanaStaff (pauta de Vaticana)
@funindex VaticanaStaff
Un tipo de @code{Staff} para la tipografía de canto gragoriano en
un estilo de notación que se asemeja al de la @cite{Editio
Vaticana}.

@item MensuralStaff (pauta de notación mensural)
@funindex MensuralStaff
Igual que @code{Staff}, excepto que está diseñado para tipografiar
piezas en estilo mensural.

@item PetrucciStaff (pauta de Petrucci)
@funindex PetrucciStaff
Una variante de @code{Staff} que se asemeja al tipografiado
mensural del @cite{Harmonices Musices Odhecaton} (Venecia, 1501)
de Ottaviano Petrucci.

@item KievanStaff (pauta de canto kievano)
@funindex KievanStaff
Igual que el contexto @code{Staff} pero adaptado para la
tipografía de piezas en el estilo del canto kievano.

@item GregorianTranscriptionStaff (pauta de transcripción de canto gregoriano)
@funindex GregorianTranscriptionStaff
Pauta para la notación de canto gregoriano en estilo moderno.

@item ChordGrid (rejilla de acordes)
@funindex ChordGrid
Crea notación de rejilla de acordes (hojas guía) en cifrado
americano.  Este contexto siempre forma parte de un contexto
@code{ChordGridScore}.

@item StandaloneRhythmStaff (pauta rítmica autocontenida)
@funindex StandaloneRhythmStaff
@funindex \rhythm
Un contexto del mismo nivel que @code{Staff}, para su uso por
parte de @code{\markup \rhythm}.

@item FretBoards (diagramas de trastes)
@funindex FretBoards
Contexto para la impresión de diagramas de trastes.

@c TODO: Add or reference an example or snippet.
@item Devnull (contexto nulo)
@funindex Devnull
Descartar discretamente cualquier información musical que se le dé
a este contexto.
@end table


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

@funindex \defaultchild
Los contextos del mismo nivel que @code{Voice} dan un valor
inicial a ciertas propiedades e inician los grabadores
correspondientes.  Un contexto del nivel más bajo es aquel que no
tiene un contexto descendiente predeterminado
@code{\defaultchild}.  Aunque es posible hacer que pueda aceptar o
contener subcontextos, éstos solo se pueden crear e introducir de
forma explícita.

@table @code
@item Voice
@funindex 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.

@item VaticanaVoice (voz de Vaticana)
@funindex VaticanaVoice
Una variante de @code{Voice} para el tipografiado de canto
gregoriano en un estilo de notación que se parece a la
@cite{Editio Vaticana}.

@item MensuralVoice (voz mensural)
@funindex MensuralVoice
Lo mismo que @code{Voice}, con modificaciones para el tipografiado
de piezas en estilo mensural.

@item PetrucciVoice (voz de Petrucci)
@funindex PetrucciVoice
Una vairante de @code{Voice} que se parece a la tipografía
mensural del @cite{Harmonices Musices Odhecaton} (Venecia, 1501)
de Ottaviano Petrucci.

@item KievanVoice (voz de kievano)
@funindex KievanVoice
Igual que el contexto @code{Voice} pero adaptado a la tipografía
de piezas en el estilo del canto kievano.

@item GregorianTranscriptionVoice (voz de transcripción gregoriana)
@funindex GregorianTranscriptionVoice
Contexto de voz para la notación de canto gregoriano en estilo
moderno.

@item Lyrics (letra)
@funindex Lyrics
Corresponde a una voz con letra.  Maneja la impresión de una sola
línea de letra.

@item VaticanaLyrics (letra de Vaticana)
@funindex VaticanaLyrics
Igual que el contexto @code{Lyrics}, excepto que provee un estilo
de enguionado en el estilo de la @cite{Editio Vaticana}: un guion
único alineado a la izquierda entre cada dos sílabas.

@item GregorianTranscriptionLyrics (letra de transcripción gregoriana)
@funindex GregorianTranscriptionLyrics
Un contexto de letra para la notación de canto gregoriano en
estilo moderno.

@item DrumVoice (voz de percusión)
@funindex DrumVoice
Una voz sobre una pauta de percusión.

@item FiguredBass (bajo cifrado)
@funindex FiguredBass
El contexto en que los objetos @code{BassFigure} se crean a partir
de la entrada escrita en el modo @code{\figuremode}.

@item TabVoice (voz de tablatura)
@funindex TabVoice
El contexto de voz utilizado dentro de un contexto
@code{TabStaff}.  Se suele dejar que se cree implícitamente.

@item CueVoice (voz de notas guía)
@funindex 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{Formatting cue notes}.  Normalmente
se deja que se cree implícitamente.

@item ChordNames (nombres de acorde)
@funindex ChordNames
Tipografía nombres de acordes.

@item NoteNames (nombres de nota)
@funindex NoteNames
Tipografía nombres de nota como su nombre indica.

@item NullVoice (voz nula)
@funindex NullVoice
Para la alineación de letras sin imprimir las notas.

@c TODO: Add or reference an example or snippet.
@item Devnull (contexto nulo)
@funindex Devnull
Descartar discretamente cualquier información musical que se le dé
a este contexto.

@item Dynamics (matices dinámicos)
@funindex Dynamics
Alberga una línea única de indicaciones de matiz dinámico,
centrada entre las pautas que rodean al propio contexto.

@item StandaloneRhythmVoice (voz rítmica autocontenida)
@funindex StandaloneRhythmVoice
@funindex \rhythm
Un contexto en el mismo nivel que @code{Voice} para su uso por
parte de @code{\markup \rhythm}.

@item Bottom (inferior)
@funindex Bottom
Es un contexto genérico del nivel inferior, aceptado por todos los
contextos de nivel intermedio.  Se puede usar para situaciones en
que la misma música tenga que aparecer, por ejemplo, en un
contexto de @code{Staff} y en otro de @code{TabStaff}.
@end table


@node Creating and referencing contexts
@section Crear y referenciar contextos

@funindex \new
@funindex \context
@cindex nuevos contextos
@cindex contextos, creación y referenciación de
@cindex referenciar contextos

LilyPond crea automáticamente contextos de nifel inferior si se
encuentra una expresión musical antes de que exista un contexto
adecuado, pero normalmente esto sólo funciona bien para partituras
sencillas o fragmentos musicales como los que aparecen en la
documentación.  Para partituras más complejas, se recomienda
especificar explícitamente todos los contextos con las
instrucciones @code{\new} o @code{\context}.  La sintaxis de estas
dos instrucciones es muy similar:

@example
[\new | \context] @var{Contexto} [= @var{nombre}] [@var{expresión_musical}]
@end example

@noindent
donde se puede especificar @code{\new} o @code{\context}.
@var{Contexto} es el tipo de contexto que se desea crear,
@var{nombre} es un nombre opcional que se da al contexto concreto
que se está creando, y @var{expresión_musical} es una sola
expresión musical que será interpretada por los complementos
grabadores y reproductores dentro de este contexto.

El prefijo @code{\new} sin ningún nombre se usa con frecuencia
para crear partituras con muchos pentagramas:

@lilypond[quote,verbatim]
<<
  \new Staff \relative {
    % leave the Voice context to be created implicitly
    c''4 c
  }
  \new Staff \relative {
    d''4 d
  }
>>
@end lilypond

@noindent
y para introducir varias voces dentro de un solo pentagrama:

@lilypond[quote,verbatim]
\new Staff <<
  \new Voice \relative {
    \voiceOne c''8 c c4 c c
  }
  \new Voice \relative {
    \voiceTwo g'4 g g g
  }
>>
@end lilypond

@noindent
@code{\new} debería usarse siempre para especificar contextos sin
nombre.

La diferencia entre @code{\new} y @code{\context} se encuentra en
la acción que se realiza:

@itemize
@item
@code{\new} con un nombre o sin él, siempre crea un contexto nuevo
y distinto, incluso si ya existe un contexto con el mismo nombre:

@lilypond[quote,verbatim]
\new Staff <<
  \new Voice = "A" \relative {
    \voiceOne c''8 c c4 c c
  }
  \new Voice = "A" \relative {
    \voiceTwo g'4 g g g
  }
>>
@end lilypond

@item
@code{\context} con un nombre especificado, crea un contexto nuevo
solamente si no existe ya un contexto del mismo tipo y con el
mismo nombre, dentro de la misma jerarquía de contextos.  En caso
contrario, se toma como referencia a dicho contexto creado
previamente, y su expresión musical se pasa a este contexto para
su interpretación.

Los contextos con nombre pueden ser útiles en casos especiales
como la letra de las canciones o los bajos cifrados,
@pxref{Working with lyrics and variables} y @rlearningnamed{Vocal
ensembles templates, Plantillas de conjuntos vocales} para el
primer caso, y @ref{Displaying figured bass} para el segundo.  De
manera más general, una aplicación de los contextos con nombre es
la separación entre la disposición de la partitura y el contenido
musical.  Son válidas culaquiera de las dos formas siguientes:

@lilypond[quote,verbatim]
\score {
  <<
    % score layout
    \new Staff <<
      \new Voice = "one" {
        \voiceOne
      }
      \new Voice = "two" {
        \voiceTwo
      }
    >>

    % musical content
    \context Voice = "one" {
      \relative {
        c''4 c c c
      }
    }
    \context Voice = "two" {
      \relative {
        g'8 g g4 g g
      }
    }
  >>
}
@end lilypond

@lilypond[quote,verbatim]
\score {
  <<
    % score layout
    \new Staff <<
      \context Voice = "one" {
        \voiceOne
      }
      \context Voice = "two" {
        \voiceTwo
      }
    >>

    % musical content
    \context Voice = "one" {
      \relative {
        c''4 c c c
      }
    }
    \context Voice = "two" {
      \relative {
        g'8 g g4 g g
      }
    }
  >>
}
@end lilypond

@noindent
De manera alternativa, se pueden utilizar variables con un efecto
similar. Véase @rlearningnamed{Organizing pieces with variables,
Organizar las piezas mediante variables}.

@item
@funindex \applyContext
@code{\context} sin ningún nombre corresponderá con el primer
contexto que se encuentre entre los creados previamente que sean
del mismo tipo dentro de la misma jerarquía de contextos, incluso
si tiene nombre, y su expresión musical se pasará a dicho contexto
para su interpretación.  Esta forma rara vez es útil.  Sin
embargo, @code{\context} sin nombre y sin expresión musical se usa
para establecer el contexto en que se ejecuta un procedimiento de
Scheme especificado con @code{\applyContext}:

@example
\new Staff \relative @{
  c'1
  \context Timing
  \applyContext #(lambda (ctx)
                   (newline)
                   (display (ly:context-current-moment ctx)))
  c1
@}
@end example

@end itemize

Un contexto debe tener un nombre si se va a hacer referencia a él
más tarde, por ejemplo cuando se asocia la letra con la música:

@example
\new Voice = "tenor" @var{música}
@dots{}
\new Lyrics \lyricsto "tenor" @var{letra}
@end example

@noindent
Para ver más detalles sobre la asociación de letra y música,
@pxref{Automatic syllable durations}.

Las propiedades de todos los contextos de un tipo en particular se
pueden modificar dentro de un bloque @code{\layout} (con una
sintaxis diferente), @pxref{Changing all contexts of the same type}.
Esta construcción también ofrece una forma de mantener las
instrucciones de disposición separadas del contenido musical.  Si
se va a modificar un solo contexto, debe usarse un bloque
@code{\with}, véase @ref{Changing just one specific context}.

@morerefs
Manual de aprendizaje:
@rlearningnamed{Organizing pieces with variables, Organizar las piezas mediante variables}.

Referencia de la notación:
@ref{Changing just one specific context},
@ref{Automatic syllable durations}.
@endmorerefs


@node Keeping contexts alive
@section Mantener vivos los contextos

@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 desaparecido,
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: dentro de una
construcción @code{@{@dots{}@}} (música secuencial), la noción que
la construcción tiene del @qq{contexto actual} descenderá un nivel
cada vez que un elemento de la secuencia finaliza en un
subcontexto del contexto anterior.  Esto evita la creación espúrea
de contextos implícitos en ciertas situaciones, pero significa que
el primer contexto dentro del que se desciende, se va a mantener
vivo hasta el final de la expresión.

Como contraste, los contextos de una expresión hecha con la
construcción @code{<<@dots{}>>} (música simultánea) no se
prolongan, por lo que si una instrucción que crea un contexto se
encierra en otro par de @code{<<@dots{}>>}, se impedirá que el
contexto persista durante toda la duración de la secuencia
@code{@{@dots{}@}} que lo contiene.

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 { d''4 d d d }
musicB = \relative { g'4 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 { a'4 a a a }
accompaniment = \relative { d'4 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 {
  s1  % skip a bar
  a'4 a a a
  s1  % skip a bar
  a4 a a a
}
accompaniment = \relative {
  d'4 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 Modifying context plug-ins
@section Modificar los complementos (plug-ins) de contexto

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

Para ver una descripción completa de todos y cada uno de los
complementos, consulte @rinternals{Engravers and Performers}. Cada
contexto que se describe en @rinternals{Contexts} 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
@funindex \consists
@funindex \remove

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

@noindent
donde cada uno de los @samp{@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,verbatim]
<<
  \new Staff \relative {
    f'2 g
  }
  \new Staff \with {
     \remove Time_signature_engraver
     \remove Clef_engraver
  } \relative {
    f'2 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
@rlearningnamed{Visibility and color of objects, Visibilidad y
color de los objetos}.

@knownissues

El orden en que los grabadores se especifican es el orden en que
se llaman para realizar su tarea de procesamiento.  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.

Las siguientes ordenaciones son importantes:

@itemize
@item
el grabador de compases @code{Bar_engraver} debe ir normalmente en
primer lugar,

@item
el grabador de digitaciones @code{New_fingering_engraver} debe ir
antes del grabador @code{Script_column_engraver} de columnas de
inscripciones,

@item
el @code{Timing_translator} debe ir antes del grabador de números
de compás @code{Bar_number_engraver}.

@end itemize

@morerefs
Archivos instalados:
@file{ly/engraver-init.ly}.
@endmorerefs


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

@cindex predeterminadas, cambio de propiedades de contexto
@cindex contexto, cambiar propiedades predeterminadas de

Se pueden cambiar las propiedades de contexto y de grob con las
instrucciones @code{\set} y @code{\override}, @pxref{Modifying
properties}.  Estas instrucciones crean eventos musicales,
haciendo que los cambios tengan efecto en el punto temporal en que
la música se está procesando.

Por contra, esta sección explica la forma de cambiarlos valores
@emph{predeterminados} de las propiedades de contexto y de grob en
el momento en que se crea el contexto.  Existen dos formas de
hacerlo.  Una modifica los valores predeterminados en todos los
contextos de un tipo dado, y el otro modifica los valores
predeterminados solamente en una instancia concreta de un
contexto.


@node Changing all contexts of the same type
@subsection Cambiar todos los contextos del mismo tipo

@cindex @code{\context} dentro de un bloque @code{\layout}
@funindex \context
@funindex \layout

Los ajustes de contexto predeterminados que se han de usar para la
composición tipográfica dentro de @code{Score}, @code{Staff},
@code{Voice} y otros contextos se pueden especificar en un bloque
@code{\context} dentro de cualquier bloque @code{\layout}.

Los ajustes para la salida MIDI, al contrario que para la
composición tipográfica, se tendrán que especificar aparte en
bloques @code{\midi} (véase
@ref{Output definitions - blueprints for contexts}).

El bloque @code{\layout} se debe colocar dentro del bloque
@code{\score} al que se aplica, después de la música.

@example
\layout @{
  \context @{
    \Voice
    [ajustes de contexto para todos los contextos Voice]
  @}
  \context @{
    \Staff
    [ajustes de contexto para todos los contextos Staff]
  @}
@}
@end example

Se pueden especificar los siguientes tipos de ajustes:

@itemize
@item
Una instrucción @code{\override}, pero omitiendo el nombre del
contexto

@lilypond[quote,verbatim]
\score {
  \relative {
    a'4^"Thicker stems" a a a
    a4 a a\ff a
  }
  \layout {
    \context {
      \Staff
      \override Stem.thickness = 4.0
    }
  }
}
@end lilypond

@item
Estableciendo una propiedad de contexto directamente

@lilypond[quote,verbatim]
\score {
  \relative {
    a'4^"Smaller font" a a a
    a4 a a\ff a
  }
  \layout {
    \context {
      \Staff
      fontSize = -4
    }
  }
}
@end lilypond

@item
Una instrucción predefinida tal como @code{\dynamicUp} o una
expresión musical como @code{\accidentalStyle dodecaphonic}.

@lilypond[quote,verbatim]
\score {
  \relative {
    a'4^"Dynamics above" a a a
    a4 a a\ff a
  }
  \layout {
    \context {
      \Voice
      \dynamicUp
    }
    \context {
      \Staff
      \accidentalStyle dodecaphonic
    }
  }
}
@end lilypond

@item
Una variable definida por el usuario que contenga un bloque
@code{\with}; para ver detalles acerca del bloque @code{\with},
@pxref{Changing just one specific context}.

@lilypond[quote,verbatim]
StaffDefaults = \with {
  fontSize = -4
}

\score {
  \new Staff {
    \relative {
      a'4^"Smaller font" a a a
      a4 a a a
    }
  }
  \layout {
    \context {
      \Staff
      \StaffDefaults
    }
  }
}
@end lilypond

@end itemize

Las instrucciones de ajuste de propiedades se pueden disponer
dentro de un bloque @code{\layout} sin que estén encerradas en un
bloque @code{\context}.  Tales ajustes son equivalentes a incluir
las mismas instrucciones de ajuste de propiedades al comienzo de
cada uno de los contextos del tipo especificado.  Si no se
especifica ningún contexto, @emph{todos y cada uno} de los
contextos del nivel inferior quedan afectados (@pxref{Bottom-level
contexts - voices}).  La sintaxis de una instrucción de ajuste de
propiedades dentro de un bloque @code{\layout} es la misma que si
la misma instrucción estuviera escrita en el propio flujo musical.

@lilypond[quote,verbatim]
\score {
  \new Staff {
    \relative {
      a'4^"Smaller font" a a a
      a4 a a a
    }
  }
  \layout {
    \accidentalStyle dodecaphonic
    \set fontSize = -4
    \override Voice.Stem.thickness = 4.0
  }
}
@end lilypond


@node Changing just one specific context
@subsection Cambiar solamente un contexto determinado

@funindex \with

Las propiedades de contexto de una única instancia de contexto
pueden cambiarse dentro de un bloque @code{\with}.  Todas las
demás instancias de contexto del mismo tipo retienen los ajustes
predeterminados que LilyPond tiene programados y que se modifican
por parte de cualquier bloque @code{\layout} que se encuentre
dentro del ámbito.  El bloque @code{\with} se debe situar
inmediatamente después de las instrucciones @code{\new}
@var{context-type}:

@example
\new Staff \with @{ [ajustes de contexto para esta instancia de contexto solamente] @}
@{
  @dots{}
@}
@end example

De forma alternativa, si la música se escribe usando la forma
corta de las instrucciones de especificación de modo, como por
ejemplo @code{\chords} en lugar de @code{\chordmode}, la
instrucción @code{\with} se debe colocar inmediatamente después de
la instrucción que especifica el modo:

@example
\chords \with @{
  [ajustes de contexto para esta instancia de contexto (implícita) solamente] @} @{
  @dots{}
@}
@end example

@noindent
dado que es el contexto implícito creado por estas formas breves
el que se quiere modificar.  Se aplica la misma consideración a
las otras formas cortas de especificar el modo de entrada
(@code{\drums}, @code{\figures}), @pxref{Input modes}.

Dado las modificaciones de contexto especificadas en bloques
@code{\with} están dentro de la música, afectarán a @emph{todas}
las salidas (tipografía @emph{y también} el MIDI), a diferencia de
los cambios que se hacen dentro de una definición de salida.

Se pueden especificar los siguientes tipos de ajustes:

@itemize
@item
Una instrucción @code{\override}, pero omitiendo el nombre del
contexto

@lilypond[quote,verbatim]
\score {
  \new Staff {
    \new Voice \with { \override Stem.thickness = 4.0 } {
      \relative {
        a'4^"Thick stems" a a a
        a4 a a a
      }
    }
  }
}
@end lilypond

@item
Estableciendo una propiedad de contexto directamente

@lilypond[quote,verbatim]
\score {
  <<
    \new Staff {
      \relative {
        a'4^"Default font" a a a
        a4 a a a
      }
    }
    \new Staff \with { fontSize = -4 } {
      \relative {
        a'4^"Smaller font" a a a
        a4 a a a
      }
    }
  >>
}
@end lilypond

@item
Una instrucción predefinida tal como @code{\dynamicUp}.

@lilypond[quote,verbatim]
\score {
  <<
    \new Staff {
      \new Voice {
        \relative {
          a'4^"Dynamics below" a a a
          a4 a a\ff a
        }
      }
    }
    \new Staff \with { \accidentalStyle dodecaphonic } {
      \new Voice \with { \dynamicUp } {
        \relative {
          a'4^"Dynamics above" a a a
          a4 a a\ff a
        }
      }
    }
  >>
}
@end lilypond

@end itemize

@morerefs
Referencia de la notación:
@ref{Input modes}
@endmorerefs


@node Order of precedence
@subsection Orden de precedencia

El valor de una propiedad que se aplica en un momento determinado
se determina de la siguiente forma:

@itemize
@item
si está en efecto una instrucción @code{\override} o @code{\set}
dentro del flujo musical, se usa dicho valor,

@item
de lo contrario, se usa el valor predeterminado tomado de un
enunciado @code{\with} en las instrucciones de inicio del
contexto,

@item
de lo contrario, se usa el valor tomado del bloque @code{\context}
más reciente que corresponda dentro de los bloques @code{\layout}
o @code{\midi},

@item
de lo contrario se usa el valor predeterminado que LilyPond lleva
preprogramado.
@end itemize

@morerefs
Manual de aprendizaje:
@rlearningnamed{Modifying context properties, Modificar las propiedades de los contextos}.

Referencia de la notación:
@ref{Contexts explained},
@ref{Bottom-level contexts - voices},
@ref{Set and unset},
@ref{Override and revert},
@ref{The layout block}.
@endmorerefs


@node Defining new contexts
@section Definir contextos nuevos

@subsubheading Panorámica de la definición de contextos

@cindex contexto, definición de nuevos
@cindex grabador, incluir en contextos

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

Los contextos específicos, como @code{Staff} y @code{Voice}, están
construidos a partir 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,

@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
    \hide Stem
    \alias Voice
  }
  \context {
    \Staff
    \accepts ImproVoice
  }
}

\relative {
  a'4 d8 bes8 \new ImproVoice { c4^"ad lib" c
   c4 c^"undress" c_"while playing :)" 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.

@funindex \name
En primer lugar es necesario definir un nombre para el nuevo
contexto:

@example
\name ImproVoice
@end example

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

@example
\alias Voice
@end example

@funindex \consists
El contexto imprimirá notas y textos explicativos, por ello
tenemos que añadir los grabadores que aportan esta funcionalidad,
y además el grabador que agrupa las notas, plicas y silencios que
están en el mismo momento musical en forma de columnas,

@example
\consists Note_heads_engraver
\consists Text_engraver
\consists Rhythmic_column_engraver
@end example

Las cabezas de todas las notas se deben situar sobre la línea
central.

@example
\consists Pitch_squash_engraver
squashedPosition = 0
@end example

El grabador @code{Pitch_squash_engraver} modifica las cabezas de
nota (creadas por el grabador @code{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 deberían parecer barras inclinadas sin plica.

@example
\override NoteHead.style = #'slash
\hide Stem
@end example

@funindex \type
@funindex Engraver_group
Todos estos complementos o plug-ins tienen que comunicarse bajo el
control del contexto.  Los mecanismos con el que se comunican los
contextos se establecen mediante la declaración del @code{\type}
(tipo) del contexto.  Dentro de un bloque @code{\layout}, casi
todos los contextos serán del tipo @code{Engraver_@/group}.
Algunos contextos especiales y los contextos de los bloques
@code{\midi} usan otros tipos.  La copia y la modificación de una
definición de contexto existente también cumplimentan el tipo.
Como este ejemplo crea una definición partiendo de cero, tiene que
ser especificada explícitamente.

@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 Rhythmic_column_engraver
  \consists Pitch_squash_engraver
  squashedPosition = 0
  \override NoteHead.style = #'slash
  \hide Stem
  \alias Voice
@}
@end example

@funindex \accepts
Los contextos dan lugar a jerarquías.  Queremos poner el contexto
@code{ImproVoice} dentro del contexto @code{Staff}, igual que los
contextos de voz 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 \inherit-acceptability
Con frecuencia, al reutilizar una definición de contexto
existente, el contexto resultante se puede usar en cualquier lugar
donde el contexto original hubiera podido hacerlo.  Si hacemos

@example
\layout @{
  @dots{}
  \inherit-acceptability @var{hacia} @var{desde}
@}
@end example

@noindent
conseguimos tener contextos del tipo @var{to} aceptados por
todos los contextos que asimismo aceptan @var{from}.  Por ejemplo,
usar

@example
\layout @{
  @dots{}
  \inherit-acceptability ImproVoice Voice
@}
@end example

@noindent
añade un @code{\accepts} para @code{ImproVoice} tanto a la
definición de @code{Staff} como a la de @code{RhythmicStaff}.

@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.

Organizar las piezas requeridas dentro de un bloque @code{\layout}
nos deja con

@example
\layout @{
  \context @{
    \name ImproVoice
    @dots{}
  @}
  \inherit-acceptability ImproVoice Voice
@}
@end example

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

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


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


@subsubheading Nuevos contextos en el MIDI

@cindex contexto, definición en el MIDI
@funindex Performer_group

En la salida MIDI, la sintaxis para definir nuevos tipos de
contexto es la misma, excepto que el bloque @code{\context} se
debe situar dentro de un bloque @code{\midi}, y el @code{\type}
tendría que ser normalmente @code{Performer_@/group} en lugar de
@code{Engraver_@/group}.  El término @dfn{engraver} (grabador) se
refiere a un plug-in o complemento de contexto que crea una cierta
salida visual. En cambio, un @dfn{performer} o intérprete es de
relevancia solamente en la salida MIDI.  Cuando los plug-ins o
complementos llevan @qq{translator} como parte del nombre en lugar
de @qq{engraver} o @qq{performer}, son relevantes tanto para la
salida gráfica como para la interpretación MIDI.  Así, cuando
estamos adaptando una definición de contexto para el bloque
@code{\midi}, tenemos que

@itemize
@item
copiarlo en un bloque @code{\midi},
@item
sustituir @code{Engraver_@/group} por @code{Performer_@/group},
@item
eliminar @code{\consists} para los engravers o grabadores (ya que
no son relevantes), y posiblemente añadir @code{\consists} para
los performers o intérpretes.
@end itemize

Tenga muy en cuenta que, para mantener una interpretación
coherente entre las salidas gráfica y de MIDI, se recomienda
copiar cualquier definición de contexto personalizada dentro de un
bloque @code{\midi}.  Como mínimo, tendría que incluir las
instrucciones que especifican la jerarquía de contextos, como
@code{\accepts}, @code{\defaultchild} y
@code{\inherit-@/acceptability}.  Se recomienda también copiar los
alias.

De manera que, para completar el ejemplo anterior, se puede añadir
lo siguiente:

@example
\midi @{
  \context @{
    \name ImproVoice
    \type Performer_group
    \alias Voice
    \consists Note_performer
    \consists Beam_performer
    \consists Dynamic_performer
    \consists Tie_performer
    \consists Slur_performer
  @}
  \context @{
    \Staff
    \accepts ImproVoice
  @}
@}
@end example

Esto hace que el contexto @code{ImproVoice} funcione también en la
salida MIDI.


@subsubheading Replacing the @code{Score} context

@cindex @code{Score}, contexto, sustitución de
@cindex contexto, nivel @code{Score}

@c This can also be done with \accepts in Global.  Since Global is
@c a very special context type, we avoid answering the question of
@c why certain things don't work on it by not mentioning it at
@c all.

Para escribir un contexto @code{MyScore} que funcione como el
contexto de nivel más alto igual que lo hace normalmente el
contexto @code{Score}, use @code{\inherit-@/acceptability MyScore
Score}.  El ejemplo siguiente define un contexto
@code{ProportionalScore} en el que está activada la notación
proporcional (@pxref{Proportional notation}).

@lilypond[verbatim,quote]
\layout {
  \context {
    \Score
    \name ProportionalScore
    \alias Score
    proportionalNotationDuration = #1/8
  }
  \inherit-acceptability ProportionalScore Score
}

music = { c'1 2 4 8 16 16 }

\new Score \music
\new ProportionalScore \music
@end lilypond

@funindex Score_engraver
@funindex Score_performer
Dado que el contexto del nivel superior debe poder contener un
cierto número de grabadores fundamentales,, la herencia de los
ajustes con @code{\Score} es lo más sencillo en casi todos los
casos.  Si, de todas formas, definimos un contexto en el nivel de
Score partiendo de cero y sin heredar la definición de
@code{Score}, el argumento de @code{\type} debe ser
@code{Score_@/engraver} (o @code{Score_@/performer} dentro de
@code{\midi}) en lugar de @code{Engraver_@/group}.  Además está
muy recomendado dar al contexto de nivel superior el alias
@code{Score}, porque varios grabadores necesitan poder acceder al
contexto superior usando su alias.


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

@cindex contexto, orden de disposición
@funindex \accepts
@funindex \denies

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án incluidos
en la lista @qq{accepts} del contexto externo se recolocan debajo
del contexto externo en lugar de anidarse dentro de él.

La lista @qq{accepts} de un contexto se puede cambiar con las
instrucciones @code{\accepts} (acepta) o @code{\denies} (niega).
@code{\accepts} añade un contexto a la lista @qq{accepts} y
@code{\denies} elimina un contexto de la lista.

Por ejemplo, un contexto @code{TabStaff} (pauta de tablatura) de
manera predeterminada @code{\accepts} (acepta) contextos
@code{TabVoice} (contextos de voz de tablatura) y @code{\denies}
(deniega) contextos @code{Voice}.  Si un contexto @code{Voice} se
escribiera dentro del @code{TabStaff}, se crearía sobre una pauta
separada.

@lilypond[verbatim,quote]
\score {
  \new TabStaff <<
    \new TabVoice { c'1 }
    \new Voice { d'1 }
  >>
}
@end lilypond

Sin embargo, usando la instrucción @code{\accepts}, se puede
forzar a @code{Voice} a que pueda estar dentro del contexto
@code{TabStaff}.

@lilypond[verbatim,quote]
\score {
  \new TabStaff <<
    \new TabVoice { c'1 }
    \new Voice { d'1 }
  >>

\layout {
    \context {
      \TabStaff
      \accepts Voice
    }
  }
}
@end lilypond

@code{\denies} se usa principalmente cuando un contexto nuevo se
está basando en otro, pero los anidamientos requeridos difieren.
Por ejemplo, el contexto @code{VaticanaStaff} está basado en el
contexto @code{Staff}, pero con el contexto @code{VaticanaVoice}
sustituido por el contexto @code{Voice} en la lista @qq{accepts}.

@cindex contexto implícito
@cindex implícito, contexto
@funindex \defaultchild

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.

Dentro de una definición de contexto, el tipo de un subcontexto
que se va a crear implícitamente se especifica usando
@code{\defaultchild} (hijo predeterminado).  Algunos eventos
musicales requieren un contexto del nivel más bajo: cuando se
encuentra este evento, se crean subcontextos de forma recursiva
hasta que se alcanza un contexto que no tiene establecido el
@code{defaultchild}.

La creación implícita de contextos puede dar lugar a pentagramas o
partituras nuevos no esperados.  La utilización de @code{\new}
para crear contextos explícitamente evita esos problemas.

@funindex alignAboveContext
@funindex alignBelowContext

En ocasiones se necesita que un contexto exista durante un breve
intervalo de tiempo, siendo un buen ejemplo el contexto de
pentagrama de un ossia.  Esto se consigue normalmente mediante la
introducción de la definición del contexto en el lugar apropiado
en paralelo con la sección correspondiente de la música principal.
De forma predeterminada, el contexto tempral se coloca debajo de
todos los contextos existentes.  Para reposicionarlo por encima
del contexto que tenga el nombre @qq{principal}, debería definirse
de esta forma:

@example
\new Staff \with @{ alignAboveContext = "principal" @}
@end example

Se presenta una situación similar cuando se posiciona un contexto
temporal de letra de una canción dentro de una disposición de
varios pentagramas tal como @code{ChoirStaff}, por ejemplo, cuando
se añade una segunda estrofa a una sección que se repite.  De
forma predeterminada, el contexto temporal de letra se coloca
debajo de los pentagramas inferiores.  Mediante la definición del
contexto temporal de letra con @code{alignBelowContext} se puede
posicionar correctamente debajo del contexto de letra con nombre
que contiene el texto de la primera estrofa.

En diversos lugares pueden verse ejemplos que muestran esta
recolocación de contextos temporales: véase
@rlearningnamed{Nesting music expressions, Anidado de expresiones
musicales}, @ref{Modifying single staves} y @ref{Techniques
specific to lyrics}.

@morerefs
Manual de aprendizaje:
@rlearningnamed{Nesting music expressions, Anidado de expresiones musicales}.

Referencia de la notación:
@ref{Modifying single staves},
@ref{Techniques specific to lyrics}.

Manual de utilización del programa:
@rprogramnamed{An extra staff appears, Aparece un pentagrama de más}.

Archivos instalados:
@file{ly/engraver-init.ly}.
@endmorerefs


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

@morerefs
Referencia de la Notación:
@ref{Naming conventions}.
@endmorerefs

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

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

@lilypond[quote,fragment,verbatim]
c''-2
@end lilypond

Si hace una visita a la documentación en busca de instrucciones de
digitación (en @ref{Fingering instructions}), 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

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

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 los
siguientes grabadores: @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 Layout interfaces
@section Interfaces de la presentación

@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 @rlearningnamed{Other sources of information, 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 . fetaText)
     (font-size . -5)           ; no superponerse cuando está junto a una cabeza.
     (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 Determining the grob property
@section Determinar la propiedad del grob

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

@lilypond[quote,fragment,verbatim]
c''-2
@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 tres @qq{espacios de pentagrama} entre la
nota y la digitación:

@example
\once \override Voice.Fingering.padding = 3
@end example

Al insertar este relleno antes de que se haya creado el objeto de
digitación, llegamos al siguiente resultado:

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

En este caso, el contexto de este truco es @code{Voice}.  Véase el
apartado dedicado al añadido @rinternals{Fingering_engraver}, que
dice:

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


@need 1500
@node Modifying properties
@chapter Modificar las propiedades

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

Dentro de cada contexto hay dos tipos diferentes de propiedades:
@dfn{propiedades de contexto} y @dfn{propiedades de grob}.  Las
propiedades de contexto se aplican a un contexto como un todo,
mientras que las propiedades de grob se usan para inicializar
objetos gráficos (grobs) impresos desde dentro de un contexto.

Las propiedades de contexto controlan la traducción de la música a
la notación.  Por ejemplo, @code{localAlterations} se usa para
determinar si hay que imprimir las alteraciones accidentales; o
@code{currentBarNumber} para determinar qué número de compás se
imprime.  También pueden cambar de valor con el tiempo durante la
interpretación de una pieza de música; @code{currentBarNumber} (el
número del compás actual) es un ejemplo obvio.

La instrucción @code{\set} (y su contrapartida @code{\unset}) se
utiliza para alterar los valores de las propiedades de contexto,
mientras que la instrucción @code{\override} (y su contrapartida
@code{\revert}) se usa para cambiar valores de las propiedades de
un grob.


@node Set and unset
@section Las instrucciones @code{\set} y @code{\unset}

@cindex propiedad, modificar
@cindex modificar propiedades
@cindex cambiar, propiedades
@cindex contexto, propiedades de
@cindex modificar contextos
@funindex \set
@funindex \unset

La sintaxis de la instrucción @code{\set} es

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

@noindent
donde @var{valor} debe ir precedido del carácter de almohadilla
@samp{#} si es un objeto de Scheme.

La sintaxis de su contrapartida, la instrucción @code{\unset}, es

@example
\unset @var{contexto}.@var{propiedad}
@end example

@noindent
Esto elimina una definición anteriormente establecida de la
@var{propiedad} del @var{contexto}.  Cualquier propiedad que haya
sido establecida dentro del @var{contexto} incluido no resulta
alterada por un @code{\unset} en el mismo contexto incluido.

Por ejemplo, los silencios multicompás se combinan en un solo
compás (como se explica en @ref{Compressing empty measures}) si la
propiedad de contexto @code{skipBars} se ha establecido a
@code{#t}:

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

Si el argumento @var{contexto} se deja sin especificar, entonces
la propiedad se establece en el contexto @q{de nivel inferior}
actual (normalmente @code{ChordNames}, @code{Voice},
@code{TabVoice}, o @code{Lyrics}).

@lilypond[quote,verbatim]
<<
  \set Score.autoBeaming = ##f
  \relative {
    e''8 e e e
    \set autoBeaming = ##t
    e8 e e e
  } \\
  \relative {
    c''8 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 un
@dfn{engraver} que usa 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, no tendrá ningún
efecto, porque skipBars es una propiedad del contexto
@code{Score}, no de @code{Voice}.

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

Los contextos son jerárquicos; cualquier cambio especificado para
un contexto que encierra a otros (p.ej. @code{Staff}) se aplica
también a todas las @code{Voice}s dentro de ese contexto
@code{Staff} en curso (suponiendo, por descontado, que el propio
contexto @code{Voice} no tiene una sobreescritura).

Todos los contextos heredan los ajustes que estén establecidos en
el contexto de nivel más alto @code{Global} (a través de
@code{\grobdescriptions}), aunque algunos de esos valores
predeterminados resultan sobreescritos dentro de sus propias
definiciones de contexto.

@lilypond[quote,verbatim]
<<
  \set Score.autoBeaming = ##t
  \relative {
    \unset autoBeaming
    e''8 e e e
    \unset Score.autoBeaming
    e8 e e e
  } \\
  \relative {
    c''8 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}.

@funindex \pushContextProperty
@funindex \popContextProperty

Tal y como se ha descrito anteriormente, @code{\unset} restaura el
valor predeterminado de una propiedad de contexto.  Sin embarco, a
veces es útil cambiar un valor durante un tiempo, y después
devolverlo al valor utilizado anteriormente.  Para este propósito
existen las dos instrucciones @code{\pushContextProperty} y
@code{\popContextProperty}: la primera inserta el valor actual en
una pila, mientras que la segunda retira un valor a partir de la
pila y restaura la propiedad a ese valor.

@lilypond[quote,verbatim]
{
  c'
  \pushContextProperty Staff.fontSize
  \set Staff.fontSize = 3
  c'
  \pushContextProperty Staff.fontSize
  \set Staff.fontSize = 6
  c'
  \popContextProperty Staff.fontSize
  c'
  \popContextProperty Staff.fontSize
  c'
}
@end lilypond


@node Override and revert
@section Las instrucciones @code{\override} y @code{\revert}

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

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}.

La sintaxis de la instrucción @code{\override} es

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

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,fragment,verbatim]
c''4 c''
\override Voice.Stem.thickness = 3.0
c''4 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,fragment,verbatim]
\override Staff.Stem.thickness = 3.0
<<
  \relative {
    e''4 e
    \override Stem.thickness = 0.5
    e4 e
  } \\
  \relative {
    c''4 c c c
  }
>>
@end lilypond

Algunas opciones susceptibles de trucaje, se llaman
@q{subpropiedades} y residen dentro de las propiedades.  Para
efectura trujajes sobre ellas, utilice instrucciones de la forma

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

o para modificar los extremos de los objetos extensos, utilice una
forma como las siguientes:

@example
\override TextSpanner.bound-details.left.text = "left text"
\override TextSpanner.bound-details.right.text = "right text"
@end example

@funindex \revert
@cindex reversión de una sobreescritura
@cindex sobreescritura, reversión

El efecto de una instrucción de sobreescritura @code{\override} se
puede deshacer con @code{\revert}; su sintaxis es

@example
\revert [@var{Contexto}.]@var{NombreDelGrob}.@var{propiedad}
@end example

Por ejemplo,

@lilypond[quote,verbatim]
\relative {
  c''4
  \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 {
    e''4
    \override Staff.Stem.thickness = 3.0
    e4 e e
  } \\
  \relative {
    c''4 c c
    \revert Staff.Stem.thickness
    c4
  }
>>
@end lilypond


@node The once command
@section La instrucción @code{\once}

@funindex \once
@cindex sobreescritura para un solo momento

@code{\once} se usa junto a las instrucciones @code{\set} o
@code{\override} para afectar solamente al instante de tiempo
actual.

@lilypond[quote,fragment,verbatim]
c''4
\once \set fontSize = 4.7
c''4
c''4
@end lilypond

@morerefs
Referencia de funcionamiento interno:
@rinternals{Backend}.
@endmorerefs


@node set versus override
@section @code{\set} frente a @code{\override}

@funindex \set
@funindex \override

Las instrucciones @code{\set} y @code{\override} manipulan
propeidades asociadas a contextos.  Las propiedades existen dentro
de una jerarquía de contextos en la que cada uno de ellos contiene
por debajo otross cero o más contextos.  Una propiedad que no se
ha establecido en un contexto específico presenta el valor que
hereda del contexto que la encierra más próximo en que se ha
establecido.

EL tiempo de vida y el valor de una propiedad de contexto son
dinámicos y solo están disponibles mientras la música se está
interpretando (esto es: @q{iterando}).  En el momento temporal de
la creación del contexto, las propiedades se incializan a partir
de sus definiciones correspondientes (junto a cualesquiera otras
modificaciones) de ese contexto.  Cualquier cambio posterior se
consigue con las instrucciones de @q{establecimiento de
propiedades} que están dentro de la propia música.

Las definiciones de Objetos Gráficos (o @qq{grobs}) son una
categoría @emph{especial} de propiedades de contexto, ya que su
uso y estructura es diferente de las propiedades de contexto
normales.  A diferencia de las propiedades de contexto normales,
las definiciones de grob se subdividen en @dfn{propiedades de
grob}.

Es más, a diferencia de las propiedades de contexto normales, las
definiciones de grob tienen su propio protocolo de mantenimiento
interno que se usa para seguir la pista de sus propieas
propiedades de grob y cualquier sub-propiedad.  Esto significa que
es posible definir aquellas partes dentro de distintos contextos y
a pesar de ello tener la definición de grob general en el momento
de la creación del grob a partir de todas las piezas aportadas
entre los contextos actual y circundantes.

Un grob se crea normalmente por parte de un grabador en el momento
de la interpretación de una expresión musical, y recibe sus
propiedades iniciales de la definición de grob en curso del
contexto del grabador.  El grabador (u otras partes de @q{backend}
LilyPond) pueden entonces cambiar (o añadirse a) las porpieades
iniciales del grob.  Sin embargo, esto no afecta a la propia
definición de grob del contexto.

Lo que LilyPond llama @emph{propiedades de grob} en el contexto de
los trucos en el @q{nivel del usuario} son realmente las
propiedades de la propia definición de grob del @emph{contexto}.

Se accede a las definiciones de grob con un conjunto de
instrucciones diferentes y se manipulan usando @code{\override} y
@code{\revert}, y tienen un nombre con la primera letra en
mayúscula (p.ej. @samp{NoteHead}); mientras que las propiedades de
contexto normales se manipulan usando @code{\set} y @code{\unset}
y su nombre empieza en letra minúscula.

@cindex @code{\tweak}, relación con  @code{\override}
@funindex \tweak
@funindex \overrideProperty

Las instrucciones @code{\tweak} y @code{\overrideProperty} cambian
las propiedades de grob puenteando completamente todas las
propiedades de contexto, y captan los grobs conforme se van
creando, fijando propieades sobre ellos para un evento de música
(@code{\tweak}) o, en el caso de @code{\overrideProperty}, para
una sobreescritura específica.


@node Tweak and single
@section Las instrucciones @code{\tweak} y @code{\single}

@funindex \tweak
@funindex \single
@cindex trucar

Cuando varios grobs tienen lugar en el mismo instante musical, no
puede usarse la instrucción @code{\override} para modificar una
sola de ellas.  En este caso se usa la instrucción @code{\tweak}.

La instrucción @code{\tweak} tiene la siguiente sintaxis:

@example
\tweak [@var{objeto-de-presentación}.]@var{propiedad-del-grob} @var{valor}
@end example

@noindent
y se aplica a la expresión musical que sigue inmediatamente a
@var{valor} dentro del flujo de la música.  Es necesario
especificar @var{objeto-de-presentación} para resolver la
ambigüedad si la expresión musical causa la creación indirecta de
grobs de distintos tipos (por ejemplo, @code{NoteHead} produce
@code{Stem}).

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

Entre los elementos que pueden aparecer más de una vez en el mismo
momento musical se encuentran 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[verbatim,fragment,quote]
< c''
  \tweak color #red
  d''
  g''
  \tweak duration-log 1
  a''
> 4
@end lilypond

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

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

El truco efectuado sobre un acorde se aplica a todas las notas que
contiene:

@lilypond[verbatim,quote]
{ \tweak color #red <c'' e''>4 }
@end lilypond

Como se mencionó anteriormente, la instrucción @code{\tweak}
sencilla no se puede usar para modificar ningún objeto que no se
haya creado directamente a partir de la entrada.  Concretamente,
no afecta a las plicas, barras automáticas ni alteraciones, porque
éstos se generan posteriormente por parte de objetos de
presentación @code{NoteHead} más que por elementos musicales del
flujo de entrada.

Tales objetos de presentación creados indirectamente se pueden
trucar usando la forma de la instrucción @code{\tweak} en que el
nombre del grob se especifica de forma explícita:

@lilypond[fragment,verbatim,quote]
\tweak Stem.color #(universal-color 'orange)
\tweak Beam.color #(universal-color 'skyblue) c''8 e''
<c'' e'' \tweak Accidental.font-size -3 ges''>4
@end lilypond

No se puede usar @code{\tweak} para modificar las claves o las
indicaciones de compás, porque éstos se separan de cualquier
instrucción @code{\tweak} precedente dentro del flujo de entrada
merced a la inserción automática de elementos adicionales que se
requieren para especificar el contexto.

Se pueden colocar varias instrucciones @code{\tweak} antes de un
elemento de notación; todos le afectan:

@lilypond[verbatim,fragment,quote]
c'
  -\tweak springs-and-rods #ly:spanner::set-spacing-rods
  -\tweak minimum-length 15
  -\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 @rextendnamed{Displaying
music expressions, 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}.

@cindex propiedades
@funindex \single
@cindex cambiar, propiedades

La instrucción @code{\single} toma una o más instrucciones
@code{\override} (que se pretende que tengan efecto en un momento
musical dado o posterior) y las convierte efectivamente en
@emph{un solo} @q{tweak} que ahora se aplica a los grobs
específicos que se han creado.

El archivo @file{ly/property-init.ly} contiene muchas definiciones
de varias instrucciones @code{\override} y pueden así ser usadas
en conjunción con la instrucción @code{\single}.  Por ejemplo, se
puede usar la función @code{\easyHeadsOn} con @code{\single} para
que afecte solo a una nota de un acorde;

@lilypond[verbatim,quote]
\relative c' {
  <\single \easyHeadsOn c' g'>2
}
@end lilypond

@morerefs
Manual de aprendizaje:
@rlearningnamed{Tweaking methods, Métodos de trucaje}.

Manual de extensión:
@rextendnamed{Displaying music expressions, Presentación de las expresiones musicales}.
@endmorerefs

@knownissues

@cindex trucar un punto de control
@cindex control, trucar un punto de

No se puede usar la instrucción @code{\tweak} para modificar los
puntos de control de una sola de varias ligaduras de unión dentro
de un acorde, aparte de la primera que se encuentre en el código
de entrada.


@node The offset command
@section La instrucción @code{\offset}

@funindex \offset
@cindex desplazamiento
@cindex valores predeterminados, desplazar

Aunque es posible fijar propiedades de grob a valores nuevos con
las instrucciones @code{\override}, @code{\tweak} y
@code{\overrideProperty}, muchas veces conviene más modificar
dichas propiedades en una cantidad relativa al valor
predeterminado.  La instrucción @code{\offset} se encuentra
disponible para este fin.

La sintaxis de @code{\offset} es

@example
[-]\offset @var{propiedad} @var{incrementos} @var{elemento}
@end example

La instrucción funciona añadiendo el contenido de
@var{incrementos} al ajuste predeterminado de la @var{propiedad}
del grob indicado por @var{elemento}.

Dependiendo de la formulación de la instrucción, @code{\offset}
puede actuar como un @code{\tweak} (trucaje) o como un
@code{\override} (sobreescritura).  Las variaciones en su uso se
explicarán después de haber examinado las propiedades de grob que
se pueden usar con @code{\offset}.

@subsubheading Propiedades que admiten el desplazamiento

Muchas, pero no todas, las propiedades de grob admiten la
aplicación de un desplazamiento.  Si @var{propiedad} no se puede
desplazar, el objeto permanece sin cambios y se emite una
advertencia.  En estos casos se deben usar en su lugar
@code{\override} o @code{\tweak} para modificar el objeto.

Se puede trabajar por ensayo y error y dejar que las advertencias
nos sirvan de guía para saber lo que puede o no puede ser
desplazado.  Sin embargo, es posible un enfoque más sistemático.

Los criterios siguientes determinan si una propiedad se puede
modificar con @code{\offset}:

@itemize

@item
La propiedad tiene un @q{ajuste predeterminado} en la descripción
del grob.  Tales propiedades aparecen listadas para cada grob en
@rinternals{All layout objects} (y también están en
@file{scm/define-grobs.scm}).

@item
La propiedad admite un valor numérico.  Entre los valores
numéricos se encuentran @code{number}, una lista de
@code{number}s, @code{number-pair}, y @code{number-pair-list}.
Las páginas de @rinternals{All layout objects} contienen una lista
de los tipos de datos característicos de cada propiedad.  No
importa si el ajuste predeterminado es una función.

@item
La propiedad no puede ser una @q{subpropiedad} (una propiedad que
reside dentro de otra propiedad).

@item
Las propiedades establecidas a valores infinitos no se pueden
desplazar. No hay ninguna forma sensata de incrementar los valores
infinitos positivos o negativos.
@end itemize

Los ejemplos siguientes tratan diversas propiedades de grob frente
a los criterios que se han expuesto.

@itemize

@item Propiedades que se pueden desplazar

@table @asis

@item @code{Hairpin.height}

Esta propiedad no es una subpropiedad, y está en la lista que
aparece en @rinternals{Hairpin}.  En cuanto a su valor, admite
@q{dimension, in staff space} (dimensión, en espacios de
pentagrama) fijado a @code{0.6666} (que claramente es un
@code{number} no infinito).

@item @code{Arpeggio.positions}

En la lista de la página que describe @rinternals{Arpeggio}
aparece una propiedad @code{positions} que admite una @q{pareja de
números}.  Su valor predeterminado es
@code{ly:arpeggio::positions}, que es un @q{callback} que se
evalúa durante la fase de tipografiado para dar como resultado una
pareja de números para cualguier objeto @code{Arpeggio} dado.

@end table

@item Propiedades que no admiten el desplazamiento

@table @asis

@item @code{Hairpin.color}

No hay un listado para @code{color} en @rinternals{Hairpin}.

@item @code{Hairpin.circled-tip}

La lista de @code{Hairpin.circled-tip} en la página de
@rinternals{Hairpin} muestra que admite un valor @code{boolean}.
Los valores booleanos so no numéricos.

@item @code{Stem.details.lengths}

Aunque está listado en @rinternals{Stem} y su valor por omisión es
una lista de @code{number}s, es una @q{subpropiedad}.  Por el
momento no se contemplan las @q{propiedades anidadas}.

@end table

@end itemize

@subsubheading @code{\offset} como sobreescritura

Si @var{elemento} es un nombre de grob como @code{Arpeggio} o
@code{Staff.OttavaBracket}, el resultado es un @code{\override} o
sobreescritura de el tipo de grob especificado.

@example
\offset @var{propiedad} @var{incremento} [@var{contexto}.]@var{NombreDeGrob}
@end example

Observe que el guión precedente @emph{nunca} se utiliza con la
forma @q{override}, de igual manera que nunca se usa con la propia
instrucción @code{\override}.

El ejemplo siguiente usa la forma @q{override}, de sobreescritura,
para alargar los arpegios predeterminados que aparecen en el
primer compás para que cubran todo el tamaño de los acordes.  Los
arpegios se amplían en medio espacio de pentagrama hacia arriba y
hacia abajo.  También se muestra la misma operación efectuada
sobre el primer acorde con una sobreescritura normal de la
propiedad @code{positions}.  Este método no es en absoluto
expresivo de la acción de @q{ampliar en medio espacio de
pentagrama}, porque los extremos se tienen que especificar
mediante coordenadas absolutas, no relativas.  Además, se
necesitarían sobreescrituras individuales para los otros acordes,
ya que varían en tamaño y posición.

@lilypond[quote,verbatim]
arpeggioMusic = {
  <c' e' g'>\arpeggio <a' c'' e''>\arpeggio
  <d' f' a' c''>\arpeggio <c' e' g' b' d'' f'' a''>\arpeggio
}

{
  \arpeggioMusic
  \bar "||"
  \offset positions #'(-0.5 . 0.5) Arpeggio
  \arpeggioMusic
  \bar "||"
  \once \override Arpeggio.positions = #'(-3.5 . -0.5)
  <c' e' g'>1\arpeggio
  \bar "||"
}
@end lilypond

@funindex \once
@funindex \temporary

En su uso como @q{override}, @code{\offset} se puede hacer
preceder por @code{\once} o por @code{\temporary} y revertirse
mediante @code{\revert} con la @var{propiedad}.  (véase
@rextendnamed{Intermediate substitution functions, Funciones de
sustitución intermedias}).  Esto se sigue a partir del hecho de
que @code{\offset} en realidad crea un @code{\override} para la
@var{propiedad}.

@lilypond[quote,verbatim]
music = { c'8\< d' e' f'\! }

{
  \music
  \offset height 1 Hairpin
  \music
  \music
  \revert Hairpin.height
  \music
  \bar "||"
  \once \offset height 1 Hairpin
  \music \music
  \bar "||"
  \override Hairpin.height = 0.2
  \music
  \temporary \offset height 2 Hairpin
  \music
  \music
  \revert Hairpin.height
  \music
  \bar "||"
}
@end lilypond

@funindex \single
@funindex \undo

Así como @code{\override}, la forma @q{override} de @code{\offset}
se puede usar con @code{\undo} y con @code{\single}.

@lilypond[quote,verbatim]
longStem = \offset length 6 Stem

{
 \longStem c'4 c''' c' c''
 \bar "||"
 \undo \longStem c'4 c''' c' c''
 \bar "||"
 \single \longStem c'4 c''' c' c''
 \bar "||"
}
@end lilypond

@subsubheading @code{\offset} como trucaje

Si @var{elemento} es una expresión musical como @code{(} o
@code{\arpeggio}, el resultado es la misma expresión musical con
un trucaje aplicado.

@example
[-]\offset [@var{NombreDeGrob}.]@var{propiedad} @var{incrementos} @var{expresión-musical}
@end example

La sintaxis de @code{\offset} en forma de @q{tweak} es análoga a
la propia instrucción @code{\tweak}, tanto en orden como en cuanto
a la presencia o ausencia del guión inicial.

El ejemplo siguiente usa la forma @q{tweak} para ajustar la
posición vertical del objeto @code{BreathingSign}.  Compárelo con
la instrucción @code{\tweak} normal que también aparece.  La
sintaxis es equivalente; sin embargo, la salida de @code{\tweak}
es menos intuitiva, ya que @code{BreathingSign.Y-offset} se
calcula a partir de la tercera línea del pentagrama.  No es
necesario saber cómo se calcula @code{Y-offset}, al usar
@code{\offset}.

@lilypond[quote,verbatim]
{
  c''4
  \breathe
  c''4
  \offset Y-offset 2 \breathe
  c''2
  \tweak Y-offset 3 \breathe
}
@end lilypond

En el ejemplo anterior, los objetos trucados se crearon
directamente a partir de la entrada del usuario: la instrucción
@code{\breathe} era una instrucción explícita para devolver un
objeto @code{BreathingSign}.  Dado que el objeto de la instrucción
no es ambiguo, no había necesidad de especificar el nombre del
objeto.  Sin embargo, cuando un objeto se crea
@emph{indirectamente}, es necesario incluir el nombre del grob.
Es lo mismo que para la instrucción @code{\tweak}.

En el ejemplo siguiente, el objeto @code{Beam} se baja en dos
espacios de pentagrama aplicando @code{\offset} a la propiedad
@code{positions}.

La primera aplicación de @code{\offset} exige que se incluya el
nombre del grob, porque nada en el código de entrada crea
explícitamente la barra.  En la segunda aplicación, la barra se
crea manualmente con la expresión musical @code{[}; por tanto, el
nombre del grob no es necesario (también aparece en la ilustración
una abreviatura: un solo número se aplica a los dos miembros de
una pareja).

@lilypond[quote,verbatim]
{
  c''8 g'' e'' d''
  \offset Beam.positions #'(-2 . -2)
  c''8 g'' e'' d''
  c''8 g'' e'' d''
  c''8-\offset positions -2 [ g'' e'' d'']
}
@end lilypond

@subsubheading @code{\offset} con objetos extensos divididos

También es posible modificar segmentos de un objeto que se
extiende sobre un salto o saltos de línea.  En este caso,
@var{offsets} admite una lista de valores del tipo de datos
requerido por la propiedad.

La instrucción @code{\offset} usada de esta forma es similar a la
instrucción @code{\alterBroken}
(véase @ref{Modifying broken spanners}).  Sin
embargo, a diferencia de @code{\alterBroken}, los valores que se
le dan a @code{\offset} son relativos, no absolutos.

El ejemplo siguiente desplaza el objeto @q{dividido}
@code{OttavaBracket} a través de su propiedad
@code{staff-padding}.  Dado que la propiedad toma un
@code{number}, se le proporciona a @var{incrementos} una lista de
números para aplicarlos a los dos segmentos creados por el salto
de línea.  La parte de corchete de la primera línea queda, en
realidad, inalterada, ya que se añade @code{0} a su valor por
omisión de @code{staff-padding}.  El segmento que está en la
segunda línea se eleva tres espacios de pentagrama a partir de su
altura por omisión.  La altura predeterminada resulta ser
@code{2}, aunque no es necesario saberlo para conseguir la
posición deseada.

@lilypond[quote,verbatim]
{
  \offset staff-padding #'(0 3) Staff.OttavaBracket
  \ottava 1
  c'''2 c'''
  \break
  c'''2 c'''
}
@end lilypond

El ejemplo siguiente copia el efecto de la instrucción
@code{\shape} mediante el incremento de la propiedad
@code{control-points} del objeto @code{Slur}.  Aquí,
@var{incrementos} es una lista de parejas de números, una por cada
segmento de la ligadura.  Este ejemplo produce un resultado
idéntico a la ilustración correspondiente que aparece en
@ref{Modifying shapes}.

@lilypond[quote,verbatim]
{
  c'4-\offset control-points #'(
               ((0 . 0) (0 . 0) (0 . 0) (0 . 1))
               ((0.5 . 1.5) (1 . 0) (0 . 0) (0 . -1.5))
              ) ( f'4 g' c''
  \break
  d'4 c'' f' c')
}
@end lilypond

Consulte @rlsrsnippet{Tweaks and overrides, Adjusting slur positions vertically}
para ver una función de Scheme @code{\offsetPositions} que
facilita el desplazamiento vertical de las ligaduras.


@node Modifying alists
@section Modificación de las listas-A

Ciertas propiedades configurables por parte del usuario se
representan internamente como @emph{listas-A} (listas
asociativas), que almacenan duplas de @emph{claves} y
@emph{valores}.  La estructura de una lista-A es la siguiente:

@example
'((@var{clave1} . @var{valor1})
  (@var{clave2} . @var{valor2})
  (@var{clave3} . @var{valor3})
  @dots{})
@end example

Si una lista-A es una propiedad de un grob o una variable de
@code{\paper}, sus claves se pueden modificar individualmente sin
que afecte a las otras claves.

Por ejemplo, para reducir el espacio entre pentagramas adyacentes
dentro de un grupo, use la propiedad @code{staff-staff-spacing}
del grob @code{StaffGrouper}.  La propiedad es una lista-A con
cuatro claves: @code{basic-distance} (distancia básica),
@code{minimum-distance} (distancia mínima), @code{padding}
(relleno) y @code{stretchability} (ampliabilidad).  Los ajustes
estándar para esta propiedad se relacionan en la sección
@qq{Backend} de la Referencia de Funcionamiento Interno (véase
@rinternals{StaffGrouper}):

@example
'((basic-distance . 9)
  (minimum-distance . 7)
  (padding . 1)
  (stretchability . 5))
@end example

Una forma de acercar los pentagramas entre sí es reducir el valor
de la clave @code{basic-distance} (@code{9}) para que se
corresponda con el valor de @code{minimum-distance} (@code{7}).
Para modificar una única clave de forma individual, utilice una
@emph{declaración anidada}:

@lilypond[quote,verbatim]
% default space between staves
\new PianoStaff <<
  \new Staff { \clef treble c''1 }
  \new Staff { \clef bass   c1   }
>>

% reduced space between staves
\new PianoStaff \with {
  % this is the nested declaration
  \override StaffGrouper.staff-staff-spacing.basic-distance = 7
} <<
  \new Staff { \clef treble c''1 }
  \new Staff { \clef bass   c1   }
>>
@end lilypond

La utilización de una declaración anidada actualiza la clave
especificada (como @code{basic-distance} en el ejemplo anterior)
sin alterar ninguna de las otras claves que ya se habían
establecido para la misma propiedad.

Ahora, supongamos que deseamos que los pentagramas estén tan
próximos como sea posible sin que se superpongan.  La manera más
sencilla de hacerlo es establecer las cuatro claves de la lista-A
a cero.  Sin embargo, no es necesario escribir cuatro
declaraciones anidadas, una por cada clave.  En lugar de eso, se
puede redefinir completamente la propiedad con una sola
declaración, como una lista-A:

@lilypond[quote,verbatim]
\new PianoStaff \with {
  \override StaffGrouper.staff-staff-spacing =
    #'((basic-distance . 0)
       (minimum-distance . 0)
       (padding . 0)
       (stretchability . 0))
} <<
  \new Staff { \clef treble c''1 }
  \new Staff { \clef bass   c1   }
>>
@end lilypond

Observe que cualquier clave que no haya sido relacionada
explícitamente en la definición de la lista-A, será reiniciada a
sus valores @emph{predeterminados si no se han fijado}.  En el
caso de @code{staff-staff-spacing}, el valor de cualquier clave no
fijada se reiniciaría a cero (excepto @code{stretchability}, que
toma el valor de @code{basic-distance} si no se fija).  Así, las
dos declaraciones siguientes son equivalentes:

@example
\override StaffGrouper.staff-staff-spacing =
  #'((basic-distance . 7))

\override StaffGrouper.staff-staff-spacing =
  #'((basic-distance . 7)
     (minimum-distance . 0)
     (padding . 0)
     (stretchability . 7))
@end example

Una consecuencia de esto (posiblemente no intencionada) es la
eliminación de cualquier valor estándar que se establezca en un
archivo de inicio y que se carga cada vez que se compila un
archivo de entrada.  En el ejemplo anterior, los ajustes estándar
para @code{padding} y @code{minimum-distance} (definidos en
@file{scm/define-grobs.scm}) se reinician a sus valores
predeterminados si no se han fijado (cero para las dos claves).
La definición de una propiedad o variable como una lista-A (de
cualquier tamaño) siempre reinicia todos los valores de clave no
establecidos a sus valores predeterminados si no se han fijado.  A
no ser que este sea el resultado deseado, es más seguro actualizar
los valores de clave individualmente con una declaración anidada.

@warning{Las declaraciones anidadas no funcionan para las listas-A
de propiedades de contexto (como @code{beamExceptions},
@code{keyAlterations}, @code{timeSignatureSettings}, etc.).  Estas
propiedades sólo se pueden modificar redefiniéndolas completamente
como listas-A.}


@node Useful concepts and properties
@chapter Conceptos y propiedades útiles

Esta sección se ocupa de varios problemas comunes de disposición y
los métodos de trucaje relacionados.

@morerefs
Manual de aprendizaje:
@rlearning{Tweaking output},
@rlearning{Other sources of information}.

Referencia de la notación:
@ref{Explaining the Internals Reference},
@ref{Modifying properties}.

Manual de extensión del programa:
@rextend{Interfaces for programmers}.

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

Fragmentos de código:
@rlsrnamed{Tweaks and overrides,Trucos y sobreescrituras}.

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

@node Direction and placement
@section Dirección y posición

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.


@node Articulation direction indicators
@subsection Indicadores de dirección de las articulaciones

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

@cindex forzada, dirección vertical, de grobs
@cindex vertical, dirección, forzada, de grobs
@cindex vertical, dirección, predeterminada, de grobs
@cindex posición, vertical, de grobs
@cindex grob, posición vertical
@cindex dirección, hacia arriba (@code{^})
@cindex dirección, hacia abajo (@code{_})
@cindex dirección, predeterminada (@code{-})
@cindex arriba, dirección (@code{^})
@cindex abajo, dirección (@code{_})
@cindex predeterminada, dirección vertical (@code{-})

@funindex -
@funindex ^
@funindex _

Se puede sobreescribir la acción predeterminada mediante el
prefijado de la articulación por un @emph{indicacor de dirección}.
Están disponibles tres indicadores de dirección: @code{^} (que
significa @qq{arriba}), @code{_} (que significa @qq{abajo}) o
@code{-} (que significa @qq{usar la dirección predeterminada}).
El indicador de dirección se puede normalmente omitir, en cuyo
caso se supone el indicador 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. @w{@code{-1}}
@item las abreviaturas de articulación, p.ej. @w{@code{-.}}, @w{@code{->}}, @w{@code{--}}
@end itemize

Estas indicaciones afectan sólo a la nota siguiente.

@lilypond[verbatim,quote]
\relative {
  c''2( c)
  c2_( c)
  c2( c)
  c2^( c)
}
@end lilypond


@node The direction property
@subsection 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 @w{@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 @w{@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:

@example
\@var{xxx}Up, \@var{xxx}Down o \@var{xxx}Neutral
@end example

@noindent
donde @code{\@var{xxx}Neutral} significa @qq{utilizar la dirección
predeterminada}.  Véase @rlearningnamed{Within-staff objects, Objetos interiores al
pentagrama}.

En alguna que otra ocasión como en el arpegio, el valor de la
propiedad @code{direction} puede especificar si el objeto se debe
colocar a la izquierda o a la derecha del objeto padre.  En este
caso @w{@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}.

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

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

En música polifónica, en general es mejor especificar una voz
explícita que cambiar la dirección de un objeto.  Para ver más
información, véase @ref{Multiple voices}.

@morerefs
Manual de aprendizaje:
@rlearningnamed{Within-staff objects, Objetos interiores al pentagrama}.

Referencia de la notación:
@ref{Multiple voices}.
@endmorerefs


@node Distances and measurements
@section Distancias y medidas

@cindex distancia, absoluta
@cindex distancia, escalada

@cindex dimensión, undades
@cindex medida, unidades
@cindex unidades, de medida

@cindex milímetros (mm)
@cindex centímetros (cm)
@cindex pulgadas (in)
@cindex puntos (pt)
@cindex puntos, grandes (bp)
@cindex grandes, puntos (bp)

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

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 la disposición de la página, y por
defecto se especifican en milímetros.  En general, las unidades de
distancia se pueden especificar añadiendo @code{\mm} (milímetros),
@code{\cm} (centímetros), @code{\in} (pulgadas), @code{\pt}
(puntos) o @code{\bp} (puntos grandes).

@indentedblock
@c U+2007 digit space characters are used to align numbers at the
@c decimal separator.
@multitable {@b{mm}} {12.3456} {1.2345} {1.2345} {12.3456} {12.3456}
@headitem
         @tab mm      @tab cm     @tab in     @tab pt       @tab bp
@item
  @b{mm} @tab  1      @tab 0.1    @tab 0.0394 @tab  2.8453  @tab  2.8346
@item
  @b{cm} @tab 10      @tab 1      @tab 0.3937 @tab 28.4528  @tab 28.3465
@item
  @b{in} @tab 25.4    @tab 2.54   @tab 1      @tab 72.27    @tab 72
@item
  @b{pt} @tab  0.3515 @tab 0.0351 @tab 0.0138 @tab  1       @tab  0.996
@item
  @b{bp} @tab  0.3538 @tab 0.0354 @tab 0.0139 @tab  1.0038  @tab  1
@end multitable
@end indentedblock

@funindex \staff-space

Las distancias de maquetación también se pueden especificar en
unidades escalables (véase el párrafo siguiente) añadiendo
@code{\staff-space} (espacios de pentagrama) a la cantidad.
@xref{Page layout} para una descripción detallada de la
maquetación o disposición de página de LilyPond.

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{Setting the staff size}.

@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
@rlearningnamed{Length and thickness of objects, Longitud y grosor
de los objetos}.

@morerefs
Manual de aprendizaje:
@rlearningnamed{Length and thickness of objects, Longitud y grosor de los objetos}.

Referencia de la notación:
@ref{Page layout},
@ref{Setting the staff size}.
@endmorerefs


@node Dimensions
@section Dimensiones

@cindex dimensión
@cindex caja circundante

Las dimensiones de un objeto gráfico especifican las posiciones de
los límites izquierdo y derecho, así como los límites inferior y
superior de las cajas limítrofes de los objetos como distancias a
partir del punto de referencia del objeto en unidades de espacios
de pentagrama.  Estas posiciones se codifican frecuentemente como
dos parejas de valores de Scheme.  Por ejemplo, la instrucción de
marcado de texto @code{\with-dimensions} toma tres argumentos, de
los cuales los dos primeros son una pareja de Scheme que da las
posiiciones de los bordes izquierdo y derecho y otra pareja de
Scheme que da las posiciones de los límites inferior y superior:

@example
\with-dimensions #'(-5 . 10) #'(-3 . 15) @var{arg}
@end example

Esto especifica una caja circundante para @var{arg} con su límite
izquierdo en -5, su límite derecho en 10, el inferior en -3 y el
superior en 15, todos ellos medidos a partir del punto de
referencia del objeto en unidades de espacios de pentagrama.

Para más información sobre la forma en que se definen estos
rectángulos, incluida la definición formal del espacio horizontal
y vertical según se establece por las instrucciones de marcado
@code{\hspace} y @code{\vspace}, véase @rextendnamed{LilyPond's box
model, El modelo de caja de LilyPond}.

@morerefs
Referencia de la notación: @ref{Other markup commands}
(documentación para instrucciones similares a
@code{\with-dimensions}, como @code{\with-dimension} o
@code{\with-dimension-from}), @ref{Distances and measurements}.
@endmorerefs


@node Spanners
@section Objetos de extensión (spanners)

@cindex spanner (objeto de extensión)
@cindex objeto, de extensión (spanner)

Muchos objetos de la notación musical se extienden a lo largo de
varias notas o incluso varios compases.  Son ejemplos las
ligaduras de expresión, las barras de corchea, los corchetes de
grupo especial, los corchetes de repetición de primera y segunda
vez, crescendi, trinos y glissandi.  Tales objetos reciben
colectivamente el nombre de @qq{spanners} u objetos de extensión,
y tienen propiedades especiales que controlan su apariencia y
comportamiento, así como métodos especiales de trucaje
relacionados con el hecho de que pueden verse fragmentados a lo
largo de varios sistemas.


@node Modifying broken spanners
@subsection Modificar objetos de extensión fragmentados

@cindex extensión, objetos de, modificar
@cindex fragmentado, objeto de extensión, modificar

Cuando un objeto de extensión cruza un salto o saltos de línea,
cada fragmento hereda los atributos del objeto de extensión
original.  Así, el trucaje ordinario de un objeto de extensión
fragmentado aplica las mismas modificaciones a cada uno de sus
segmentos.  En el ejemplo que aparece a continuación, la
sobreescritura de la propiedad @code{thickness} afecta a la
ligadura de expresión a ambos lados del salto de línea.

@lilypond[verbatim,quote,ragged-right]
\relative c'' {
  r2
  \once\override Slur.thickness = 10
  c8( d e f
  \break
  g8 f e d) r2
}
@end lilypond

@funindex \alterBroken

Es posible modificar independientemente la apariencia de los
fragmentos individuales de un elemento de extenssión fragmentado
con la instrucción @code{\alterBroken}.  Esta instrucción puede
producir o bien un @code{\override} (sobreescritura) o un
@code{\tweak} (trucaje) de una propiedad del elemento extenso.

La sintaxis de la instrucción @code{\alterBroken} es

@example
[-]\alterBroken @var{propiedad} @var{valores} @var{objetivo}
@end example

@noindent
El argumento @var{valores} es una lista de valores, uno por cada
fragmento.  Si @var{objetivo} es el nombre de un grob como
@code{Slur} o @code{Staff.PianoPedalBracket}, el resultado es un
@code{\override} del tipo de grob especificado.  Si @var{objetivo}
es una expresión musical como @samp{(} o @samp{[}, el resultado es
la misma expresión musical con el trucaje arpopiado aplicado.

Se debe usar el guion inicial con la forma @code{\tweak}.  No lo
escriba cuando use @code{\alterBroken} como un @code{\override}.

@funindex \once
@funindex \temporary

En su uso como @code{\override}, @code{\alterBroken} may be
prefaced by @code{\once} or @code{\temporary} and reverted by
using @code{\revert} with @var{property} (see
@rextend{Intermediate substitution functions}).

El código siguiente aplica una sobreescritura @code{\override}
independiente a cada uno de los segmentos de ligadura de expresión
del ejemplo anterior:

@lilypond[verbatim,quote,ragged-right]
\relative c'' {
  r2
  \alterBroken thickness #'(10 1) Slur
  c8( d e f
  \break
  g8 f e d) r2
}
@end lilypond

Se puede usar la instrucción @code{\alterBroken} con cualquier
objeto de extensión, incluyendo @code{Tie} (ligadura de unión),
@code{PhrasingSlur} (ligadura de fraseo), @code{Beam} (barra de
corchea) y @code{TextSpanner} (elemento extenso de texto).  Por
ejemplo, un editor que se encuentra preparando una edición crítica
podría desear indicar la ausencia de parte de una ligadura de
fraseo en una fuente haciendo discontinuo solamente el segmenteo
que se ha añadido.  El ejemplo siguiente ilustra cómo se puede
conesguir, en este caso usando la forma @code{\tweak} de la
instrucción:

@lilypond[verbatim,quote,ragged-right]
% The empty list is conveniently used below, because it is the
% default setting of dash-definition, resulting in a solid curve.
\relative {
  c''2-\alterBroken dash-definition #'(() ((0 1.0 0.4 0.75))) \(e
  \break
  g2 e\)
}
@end lilypond

Es importante comprender que @code{\alterBroken} establece cada
fragmento de un objeto de extensión dividido, al valor
correspondiente dentro de @var{valores}.  Cuando hay menos valores
que fragmentos, se asigna una lista vacía a cualquier fragmento
adicional.  Esto puede conducir a resultados no deseados si la
propiedad de presentación no está establecida a la lista vacía de
forma predeterminada.  En estos casos, se debería asignar un valor
apropiado a cada segmento.

Pueden producirse saltos de lína en diferentes lugares como
resultado de los cambios en la disposición.  Los ajustes elegidos
para @code{\alterBroken} podrían no ser adecuados para un objeto
de extensión que ya no se encuentra dividido, o uno que está
dividido en más segmentos que antes.  Un uso explícito de
@code{\break} puede prevenir esta situación.

La instrucción @code{\alterBroken} no es efectiva para propiedades
de objetos de extensión accedidos antes del salto de línea, como
@code{direction}.

@morerefs
Manual de extensión de LilyPond:
@rextend{Difficult tweaks}.
@endmorerefs


@node Setting minimum lengths for spanners
@subsection Establecimiento de longitudes mínimas para los objetos de extensión

La interfaz @code{spanner-interface} provee tres propiedades que
se aplican a varios objetos de extensión.

@subsubheading La propiedad @code{minimum-length} (longitud mínima)

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
About: 'minimum-length and 'minimum-length-after-break
Works for:
  Tie
  MultiMeasureRest
  Hairpin
  Slur
  PhrasingSlur

Works as long as callback is made:
  Glissando
  Beam
  TextSpanner
  TrillSpanner

Works not at all for:
  LyricSpace
  LyricHyphen
  LyricExtender
  System

@end ignore

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

@lilypond[verbatim,quote]
\relative \compressMMRests {
  a'1
  R1*23
  % increase the length of the rest bar
  \once \override MultiMeasureRest.minimum-length = 20
  R1*23
  a1
}
@end lilypond

@lilypond[verbatim,quote]
\relative {
  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 {
  a'( g)
  a
  -\tweak minimum-length 5
  ( g)

  a\( g\)
  a
  -\tweak minimum-length 5
  \( g\)
}
@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,fragment,quote]
% 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,fragment,quote]
% not effective alone
\once \override Beam.minimum-length = 20
e'8 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
e'8 e' e' e'
@end lilypond

@subsubheading La propiedad @code{minimum-length-after-break}

Se puede usar la propiedad @code{minimum-length-after-break} para
ampliar objetos de extensión fragmentados que comienzan después de
un salto de línea.  Respecto a la propiedad @code{minimum-length},
es necesaria con frecuencia para establecer la propiedad
@code{springs-and-rods} al valor
@code{ly:spanner::set-spacing-rods}.

@lilypond[verbatim,quote,ragged-right]
{
  \once \override Tie.minimum-length-after-break = 20
  a1~
  \break
  a1

  \once \override Slur.minimum-length-after-break = 20
  a1(
  \break
  d'1)

  \once \override TextSpanner.springs-and-rods =
    #ly:spanner::set-spacing-rods
  \once \override TextSpanner.minimum-length-after-break = 20
  a1\startTextSpan
  \break
  a1\stopTextSpan

  \once \override Hairpin.after-line-breaking = ##t
  \once \override Hairpin.to-barline = ##f
  \once \override Hairpin.minimum-length-after-break = 20
  a1\<
  \break
  a1\!

  \once \override Glissando.springs-and-rods =
    #ly:spanner::set-spacing-rods
  % for completeness; not necessary for manual breaks
  \once \override Glissando.breakable = ##t
  \once \override Glissando.after-line-breaking = ##t
  \once \override Glissando.minimum-length-after-break = 20
  a1\glissando
  \break
  d'1
}
@end lilypond

@node Controlling spanner end points
@subsection Control de los puntos extremos de un objeto de extensión

La propiedad @code{to-barline} (hasta la línea divisoria) de la
interfaz @code{spanner-interface}, con un valor predeterminado que
normalmente es @code{#t}, hace que los reguladores y otros objetos
de extensión finalicen sobre la primera nota de un compás en lugar
de hacerlo sobre la línea divisoria inmediatamente anterior.  Si
se establece al valor @code{#f}, el objeto de extensión se expande
más allá de la barra de compás y termina sobre la propia nota:

@lilypond[verbatim,quote]
\relative {
  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.


@node Line styles
@section Estilos de línea

La interfaz @rinternals{line-interface} engloba a todos los
objetos que imprimen líneas.  Todos los objetos que contemplan
estas interfaces se pueden imprimir usando distintos estilos de
línea.  He aquí un ejemplo que muestra los valores que están
disponibles.

@lilypond[ragged-right,verbatim,quote]
\relative {
  d''2 \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

Algunos objetos pueden contemplar estilos específicos adicionales.


@node Line spanners
@section Líneas de extensión

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

Las posiciones de los dos puntos extremos del objeto de extensión
se calculan sobre la marcha, pero es posible sobreescribir sus
coordenadas Y.  Las propiedades que hay que especificar están
anidadas dos niveles más abajo dentro de la jerarquía de
propiedades, pero la sintaxis de la instrucción @code{\override}
es bastante sencilla:

@lilypond[quote,fragment,verbatim]
e''2 \glissando b'
\once \override Glissando.bound-details.left.Y = 3
\once \override Glissando.bound-details.right.Y = -2
e''2 \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[ragged-right,fragment,verbatim,quote]
\override Glissando.bound-details.right-broken.Y = -3
c''1 \glissando \break
f''1
@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, medida 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 @w{@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)
@funindex \startTextSpan
@funindex \stopTextSpan

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

@lilypond[quote,ragged-right,fragment,verbatim]
\override TextSpanner.bound-details.left.text
   = \markup { \small \bold Slower }
\relative { c''2\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[quote,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"

\relative { c'4^\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
@w{@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

@funindex \endSpanners
@funindex \startTextSpan
@funindex \stopTextSpan

La función musical @code{\endSpanners} da por terminados
prematuramente todos los objetos de extensión que están en el
argumento, obedeciendo la propiedad @code{to-barline} (hasta la
barra), si está establecida.

@lilypond[verbatim,quote,ragged-right]
\relative c'' {
  \endSpanners c1 \> c
  \endSpanners { r4 c2.\< c1\startTextSpan } c1 c
}
@end lilypond

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

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


@node Visibility of objects
@section Visibilidad de los objetos

@cindex objeto, visibilidad
@cindex grob, visibilidad
@cindex visibilidad de un objeto

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
@rlearningnamed{Visibility and color of objects, 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.


@node Removing the stencil
@subsection Eliminar el sello

@cindex sello, eliminar
@funindex \omit

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,fragment,verbatim]
a1 a
\override Score.BarLine.stencil = ##f
a a
\revert Score.BarLine.stencil
a a a
@end lilypond

Esta operación, bastante común, tiene la forma abreviada
@code{\omit} como atajo:

@lilypond[quote,fragment,verbatim]
a1 a
\omit Score.BarLine
a a
\undo \omit Score.BarLine
a a a
@end lilypond

@node Making objects transparent
@subsection Hacer transparentes los objetos

@cindex transparentes, hacer los objetos
@funindex \hide

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,fragment,verbatim]
a'4 a'
\once \override NoteHead.transparent = ##t
a' a'
@end lilypond

Esta operación, bastante común, tiene la forma abreviada @code{\hide}
como atajo:

@lilypond[quote,fragment,verbatim]
a'4 a'
\once \hide NoteHead
a' a'
@end lilypond

@node Painting objects white
@subsection Pintar los objetos de blanco

@cindex objeto, coloreado de
@cindex coloreado de un objeto
@cindex capa
@cindex impresión, orden de
@cindex sobreescritura de un objeto
@cindex objeto, sobreescritura de
@cindex grob, sobreescritura de
@cindex whiteout (circundado en blanco)
@cindex grob, y circundado en blanco (whiteout)

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,fragment,verbatim]
\override Staff.Clef.color = #white
a'1
@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
@w{@code{-1}}, para que se dibuje antes:

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

@snippets
@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
{snippets/using-the-whiteout-property.ly}

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

@c TODO Add making other objects breakable

@funindex 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
@rlearningnamed{Visibility and color of objects, 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:

@indentedblock
@multitable {@code{begin-of-line-invisible}} {@code{#(#t #t #t)}} {Antes del} {Si no hay} {Después del}
@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
@end indentedblock

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:

@indentedblock
@multitable {@code{DoublePercentRepeat}} {@b{Contexto usual}} {@code{begin-of-line-invisible}}
@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{Divisio}             @tab @code{Staff}          @tab @code{begin-of-line-invisible}
@item @code{DoublePercentRepeat} @tab @code{Voice}          @tab @code{begin-of-line-invisible}
@item @code{KeyCancellation}     @tab @code{Staff}          @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{ClefModifier}       @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
@end indentedblock

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

@lilypond[quote,verbatim,ragged-right]
\relative {
  f'4 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
@emph{primera} línea a no ser que su valor establecido sea
distinto de @code{1}.

@item Clave: véase la sección siguiente.

@item
Las repeticiones dobles de tipo porcentaje se imprimen todas
siempre o bien no se imprimen nunca.  Utilice @code{begin-@/of-@/line-@/invisible} para imprimirlas y @code{all-@/invisible} para
suprimirlas.

@item Armadura: véase la sección siguiente.

@item ClefModifier: véase la sección siguiente.
@end itemize


@node Special considerations
@subsection Consideraciones especiales

@subsubheading Visibilidad después de un cambio explícito

@cindex armadura, visibilidad después de un cambio explícito
@funindex explicitKeySignatureVisibility
@cindex clave, visibilidad después de un cambio explícito
@funindex 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,ragged-right]
\relative {
  \key g \major
  f'4 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,ragged-right]
\relative {
  \key g \major
  f'4 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

@subsubheading Visibilidad de las alteraciones de precaución

Para eliminar las alteraciones de cancelació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,ragged-right]
\relative {
  \key g \major
  f'4 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.

Observe que al modificar la tonalidad a Do@tie{}mayor o
La@tie{}menor, las alteraciones de cancelación serían @emph{la
única} indicación del cambio de armadura.  En este caso, el
establecimiento de @code{printKeyCancellation} al valor @code{#f}
no tiene ningún efecto:

@lilypond[quote,verbatim,ragged-right]
\relative {
  \key g \major
  f'4 g a b
  \set Staff.explicitKeySignatureVisibility = #all-invisible
  \set Staff.printKeyCancellation = ##f
  \key c \major
  f4 g a b \break
  f4 g a b
  f4 g a b
}
@end lilypond

En lugar de ello, para suprimir las alteraciones de cancelación
aún cuando la armadura cambia a Do@tie{}mayor o a La@tie{}menor,
sobreescriba la visibilidad del grob @code{KeyCancellation}:

@lilypond[quote,verbatim,ragged-right]
\relative {
  \key g \major
  f'4 g a b
  \set Staff.explicitKeySignatureVisibility = #all-invisible
  \override Staff.KeyCancellation.break-visibility = #all-invisible
  \key c \major
  f4 g a b \break
  f4 g a b
  f4 g a b
}
@end lilypond

@c TODO Add visibility of cautionary accidentals before notes

@subsubheading Claves transportadas

@cindex transportada, visibilidad de una clave
@cindex visibilidad de una clave transportada
@cindex clave, visibilidad de la transposición

El pequeño símbolo de transposición sobre una clave se produce por
parte del objeto @code{ClefModifier}.  Su visibilidad se hereda
automáticamente de la del objeto @code{Clef}, así que no es
necesario aplicar las sobreescrituras correspondientes
@code{break-visibility} a los objetos @code{ClefModifier} para
suprimir los símbolos de transposición u octavación para las
claves invisibles.

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

@morerefs
Manual de aprendizaje:
@rlearningnamed{Visibility and color of objects, Visibilidad y color de los objetos}
@endmorerefs


@node Rotating objects
@section Rotación de objetos

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.


@node Rotating layout objects
@subsection Rotación de objetos de presentación

@cindex rotar un objeto
@cindex objeto, rotación

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 regulador en ángulo
@cindex @'angulo, regulador 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,fragment,verbatim]
g4\< e' d'' f''\!
\override Hairpin.rotation = #'(15 -1 0)
g4\< e' d'' f''\!
@end lilypond

@node Rotating markup
@subsection Rotación de elementos de marcado

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,fragment,verbatim]
\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 Aligning objects
@section Alineación de objetos

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.

@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}.  La
sobreescritura de las propiedades @code{X-offset} ó
@code{Y-offset} a un valor fijo hace que se descarte la respectiva
propiedad @code{self-alignment}.}

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.

@morerefs
Referencia de la notación:
@ref{Using the break-alignable-interface}.

Manual de extensión:
@rextendnamed{Callback functions, Funciones de callback}.
@endmorerefs


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

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,fragment,quote]
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 Using the side-position-interface
@subsection Uso del @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

@indentedblock
@multitable {@b{propiedad @code{side-axis}}} {@b{propiedad @code{direction}}} {@b{colocación}}
@headitem propiedad @code{side-axis}
                            @tab propiedad @code{direction}
                                                   @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
@end indentedblock

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 Using the self-alignment-interface
@subsection Uso del @code{self-alignment-interface}

@subsubheading 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 @w{@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 @w{@code{-1}}, @code{0} y @code{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,fragment]
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

@subsubheading 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
@w{@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 @w{@code{-1}},
@code{0} y @code{1}, respectivamente.

@subsubheading 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 dela nota.

@lilypond[quote,verbatim,fragment]
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
@subsection 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
@subsection 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 Using the break-alignable-interface
@subsection Uso del @code{break-alignable-interface}

@cindex alineación a un objeto
@funindex break-align-symbols

Las llamadas de ensayo y de texto, los números de compás, y de
forma más general todos los objetos con la interfaz
@rinternals{break-alignable-interface}, a los cuales nos referimos
colectivamente como @qq{objetos alineables en el salto de línea},
se pueden alinear con objetos de notación tales como líneas
divisorias, armaduras de tonalidad, indicaciones de compás y de
forma general con cualquier objeto que tenga la interfaz
@rinternals{break-aligned-interface}.  Para ser más exactos, los
elementos break-aligned (alineados con el salto) tienen una
propiedad @code{break-@/align-@/symbol}, que aporta símbolos que
se pueden usar como @q{puntos de anclaje} para otros objetos por
medio de la propiedad @code{break-@/align-@/symbols}.  Consulte
@rinternals{break-alignment-interface} para ver una lista completa
de los símbolos disponibles.

Cada tipo de objeto tiene su propio punto de referencia
predeterminado, con el que se alinean las marcas de ensayo:

@lilypond[verbatim,quote,fragment]
\override Score.TextMark.self-alignment-X = #CENTER
% The text mark will be aligned
% to the right edge of the clef
\override Score.TextMark.break-align-symbols =
            #'(clef)
\key a \major
\clef treble
\textMark "↓"
e'1
% The text mark will be aligned
% to the left edge of the time signature
\override Score.TextMark.break-align-symbols =
            #'(time-signature)
\key a \major
\clef treble
\time 3/4
\textMark "↓"
e'2.
% The text mark will be centered
% above the breathing mark
\override Score.TextMark.break-align-symbols =
            #'(breathing-sign)
\key a \major
\clef treble
\time 4/4
e'1
\breathe
\textEndMark "↓"
@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,fragment]
\override Score.TextMark.self-alignment-X = #CENTER
% The text mark will be aligned
% to the right edge of the key signature
\override Score.TextMark.break-align-symbols =
            #'(key-signature clef)
\key a \major
\clef treble
\textMark "↓"
e'1
% The text mark will be aligned
% to the right edge of the clef
\set Staff.explicitKeySignatureVisibility = #all-invisible
\override Score.TextMark.break-align-symbols =
            #'(key-signature clef)
\key a \major
\clef bass
\textMark "↓"
gis,1
% The text mark will be centered
% above the bar line
\set Staff.explicitKeySignatureVisibility = #all-invisible
\set Staff.explicitClefVisibility = #all-invisible
\override Score.TextMark.break-align-symbols =
            #'(key-signature clef)
\key a \major
\clef treble
\textMark "↓"
e'1
@end lilypond

La alineación del elemento break-alignable 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,fragment]
\override Score.TextMark.self-alignment-X = #CENTER
% The text mark will be aligned
% with the right edge of the key signature
\override Score.TextMark.break-align-symbols =
            #'(key-signature)
\key a \major
\clef treble
\time 4/4
\textMark "↓"
e'1
% The text mark will be centered
% above the key signature
\once \override Score.KeySignature.break-align-anchor-alignment =
                  #CENTER
\textMark "↓"
\key a \major
e'1
% The text mark will be aligned
% with the left edge of the key signature
\once \override Score.KeySignature.break-align-anchor-alignment =
                  #LEFT
\key a \major
\textMark "↓"
e'1
@end lilypond

El elemento break-alignable también se puede desplazar al borde derecho o
izquierdo en una medida arbitraria.  Las unidades son espacios de
pentagrama:

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


@node Modifying stencils
@section Modificación de los sellos

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{Graphic notation inside markup}.

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 {
  a' a \XinO a a
}
@end lilypond

Cualquiera de los glifos de @emph{Feta} usados en la fuente
tipográfica Emmentaler se puede pasar a la instrucción de marcado
@code{\musicglyph}: véase @ref{The Emmentaler font}.

Se pueden insertar en línea tanto imágenes en formato @file{EPS}
como instrucciones de PosrtScript usando las instrucciones de
marcado @code{\epsfile} y @code{\postscript} respectivamente;
véase @ref{Graphical markup}.


@morerefs
Referencia de la notación:
@ref{Graphic notation inside markup},
@ref{Formatting text},
@ref{Text markup commands},
@ref{The Emmentaler font},
@ref{Graphical markup}.
@endmorerefs


@need 1500
@node Modifying shapes
@section Modificación de las formas


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

@cindex ligadura de expresión, modificar
@cindex ligadura de unión, modificar
@cindex Bézier, curva de, puntos de control
@cindex puntos de control en curvas de Bézier

Las ligaduras de unión (@code{Tie}s), de expresión (@code{Slur}s),
de fraseo (@code{PhrasingSlur}s), de dejar vibrar
(@code{LaissezVibrerTie}s) y de repetición (@code{RepeatTie}s) 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 de dos formas:

@enumerate a
@item
mediante la especificación de los desplazamientos que se quieren
realizar sobre los puntos de control de la curva de Bézier
calculada automáticamente, o bien

@item
mediante la especificación explícita de las posiciones de los
cuatro puntos de control que se requieren para definir la curva
deseada.
@end enumerate

A continuación se explican ambos métodos.  El primer método es más
adecuado cuando solo se requieren ligeros ajustes de la curva; el
segundo puede ser mejor para crear curvas que tienen relación con
una única nota.

@subsubheading Curvas de Bézier cúbicas

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 y la imagen 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.

@lilypond
\markup \pad-around #0.5
\score {
  \new Staff \with {
    \remove Staff_symbol_engraver
    \remove Clef_engraver
    \remove Time_signature_engraver
  }
  \new Voice \with {
    \hide NoteHead
    \omit Stem
  }
  {
    \vshape #'((-2 . 0) (-1 . 2) (1 . 1.5) (2 . -2)) Slur
    c( c)
  }
}
@end lilypond

Todas las traslaciones, rotaciones y escalado de los puntos de
control producen exactamente las mismas operaciones sobre la
curva.



@subsubheading Especificar desplazamientos a partir de los puntos de control actuales

@cindex conformar ligaduras
@funindex \shape

En este ejemplo, la colocación automática de la ligadura no
resulta óptima, y @code{\tieDown} no es la solución.

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

El ajuste de los puntos de control de la ligadura mediante la
instrucción @code{\shape} permite evitar las colisiones.

La sintaxis de @code{\shape} es:

@example
[-]\shape @var{desplazamientos} @var{elemento}
@end example

Esta instrucción recoloca los puntos de control de @var{elemento}
en las cantidades dadas por @var{desplazamientos}.  El argumento
@var{desplazamientos} es una lista de parejas de números o una
lista de tales listas.  Cada elemento de una pareja representa el
desplazamiento de una de las coordenadas de un punto de control.
Si el @var{elemento} es una cadena de caracteres, el resultado es
@code{\once\override} para el tipo de grob especificado.  Si
@var{elemento} es una expresión musical, el resultado es la misma
expresión musical con la consiguiente modificación aplicada.

En otras palabras, la función @code{\shape} puede actuar como una
instrucción @code{\once\override} o como una instrucción
@code{\tweak} dependiendo de si el argumento @var{elemento} es el
nombre de un grob, como @qq{Slur}, o una expresión musical, como
@qq{(}.  El argumento @var{desplazamientos} especifica los
desplazamientos de los cuatro puntos de control como una lista de
cuatro parejas de valores (dx . dy) en unidades de espacios de
pentagrama (o una lista de tales listas si la curva tiene más de
un segmento).

El guión precedente se exige si, y sólo si, se usa la forma
@code{\tweak}.

Así, usando el mismo ejemplo de arriba y la forma
@code{\once\override} de la instrucción @code{\shape}, lo
siguiente tiene el efecto de elevar la ligadura de unión en la
mitad de un espacio de pentagrama:

@lilypond[verbatim,quote]
<<
  {
    \shape #'((0 . 0.5) (0 . 0.5) (0 . 0.5) (0 . 0.5)) Tie
    e'1~ 1
  }
\\
  \relative { r4 <g' c,> <g c,> <g c,> }
>>
@end lilypond

Este posicionamiento de la ligadura de unión es mejor, pero quizá
debería elevarse más en la parte central.  El ejemplo siguiente
hace esto, esta vez usando la forma alternativa @code{\tweak}:

@lilypond[verbatim,quote]
<<
  {
    e'1-\shape #'((0 . 0.5) (0 . 1) (0 . 1) (0 . 0.5)) ~ e'
  }
\\
  \relative { r4 <g' c,> <g c,> <g c,> }
>>
@end lilypond

@funindex \vshape

Como ayuda para el proceso de trucaje, se ofrece la función
@code{\vshape}.  Su nombre significa @emph{forma visual}: actúa
exactamente igual que @code{\shape}, excepto que los puntos y el
polígono de control se imprimen por añadidiura.

@lilypond[verbatim,quote,ragged-right]
\relative {
  c''8(\( a) e4 gis a\)
  \vshape #'((0 . -0.3) (0.5 . -0.2)
             (0.5 . -0.3) (0 . -0.7)) PhrasingSlur
  c8(\( a) e4 gis a\)
}
@end lilypond

Se recomienda empezar con @code{\vshape} e ir ajustando hasta que
se consigue una curva satisfactoria, para después sencillamente
borrar la letra @qq{v} de la instrucción @code{\vshape}.

También es posible dar forma a dos curvas diferentes que dan
comienzo en el mismo momento musical:

@lilypond[verbatim,quote,ragged-right]
\relative {
  c''8(\( a) a'4 e c\)
  \shape #'((0.7 . -0.4) (0.5 . -0.4)
            (0.3 . -0.3) (0 . -0.2)) Slur
  \shape #'((0 . 0) (0 . 0.5)
            (0 . 0.5) (0 . 0)) PhrasingSlur
  c8(\( a) a'4 e c\)
}
@end lilypond

La función @code{\shape} también puede desplazar los puntos de
control de las curvas que se extienden atravesando saltos de
línea.  Cada pieza de la curva dividida puede recibir su propia
lista de desplazamientos.  Si no se necesita hacer cambios a uno
de los segmentos en particular, se puede usar una lista vacía como
contenedor.  En este ejemplo, el salto de línea hace que la única
ligadura de expresión aparezca como si fueran dos:

@lilypond[verbatim,quote,ragged-right]
\relative {
  c'4( f g c
  \break
  d,4 c' f, c)
}
@end lilypond

Los cambios en la forma de las dos mitades de la ligadura de
expresión deja más claro que la ligadura continúa más allá del
salto de línea:

@lilypond[verbatim,quote,ragged-right]
% () may be used as a shorthand for ((0 . 0) (0 . 0) (0 . 0) (0 . 0))
% if any of the segments does not need to be changed
\relative c' {
  \shape #'(
             (( 0 . 0) (0 . 0) (0 . 0) (0 . 1))
             ((0.5 . 1.5) (1 . 0) (0 . 0) (0 . -1.5))
           ) Slur
  c4( f g c
  \break
  d,4 c' f, c)
}
@end lilypond

En una curva en forma de «S» siempre es necesario ajustar
manualmente los puntos de control: LilyPond nunca escoge tales
formas automáticamente.

@lilypond[verbatim,quote]
\relative c'' {
  c8( e b-> f d' a e-> g)
  \shape #'((0 . -1) (5.5 . -0.5) (-5.5 . -10.5) (0 . -5.5))
         PhrasingSlur
  c8\( e b-> f d' a e-> g\)
}
@end lilypond

@subsubheading Especificar los puntos de control explícitamente

Las coordenadas de los puntos de contro de Bézier se especifican
en unidades de espacios de pentagrama.  La coordenada@tie{}X es
relativa al punto de referencia al que se adjunta la ligadura, y
la coordenada@tie{}Y es relativa a la línea central del
pentagrama.  Las coordenadas se especifican como una lista de
cuatro parejas de números decimales (reales).  Un enfoque consiste
en estimar las coordenadas de los dos extremos, y después adivinar
los dos puntos intermedios.  Los valores óptimos se encuentran
después por ensayo y error.  Tenga en cuenta que estos valores
podrían requerir un ajuste manual si se hace posteriormente
cualquier cambio manual a la música o a la disposición.

Una situación en la que es preferible especificar los puntos de
control explícitamente a especificar los desplazamientos es cuando
se necesita especificarlos de forma relativa a una nota única.  A
continuación presentamos un ejemplo de esto.  Muestra una forma de
indicar una ligadura que se extiende hacia el interior de las
casillas de primera y segunda vez de una repetición.

@lilypond[verbatim,quote]
\relative {
  c''1
  \repeat volta 3 { c4 d( e f }
  \alternative {
    \volta 1 { g2) d }
    \volta 2 {
      g2
        % create a slur and move it to a new position
        % the <> is just an empty chord to carry the slur termination
        -\tweak control-points
                  #'((-2 . 3.8) (-1 . 3.9) (0 . 4) (1 . 3.4)) ( <> )
      f,
    }
    \volta 3 {
      e'2
        % create a slur and move it to a new position
        -\tweak control-points
                  #'((-2 . 3) (-1 . 3.1) (0 . 3.2) (1 . 2.4)) ( <> )
      f,
    }
  }
}
@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}.  Sin embargo, se puede sobreescribir la
propiedad @code{tie-configuration} de @code{TieColumn} para fijar
la línea de inicio y la dirección según se requiera.

@morerefs
Referencia de funcionamiento interno:
@rinternals{TieColumn}.
@endmorerefs
