Update translated docs internalsref -> rinternals

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

@c -*- coding: utf-8; mode: texinfo; documentlanguage: es -*-
@c This file is part of lilypond.tely
@ignore
    Translation of GIT committish: 2c2b739a8f4c1998ffb6423d1d73350426ec59be

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  See TRANSLATION for details.
@end ignore

@c \version "2.11.38"

@node Changing defaults
@chapter Changing defaults


El objetivo del diseño de LilyPond es proporcionar por defecto la más alta
calidad de los resultados.  A pesar de ello, podría tener que cambiar
este resultado por defecto.  La disposición sobre el papel se controla a través de un amplio número
de proverbiales @q{botones e interruptores.}  Este capítulo no
relaciona todos y cada uno de los botones.  Más bien da una visión de conjunto sobre qué grupos de controles
se encuentran disponibles y explica la forma de hallar el botón exacto que se debe utilizar para conseguir
un determinado efecto.


@cindex Referencia de funcionamiento interno

Los controles disponibles para los ajustes finos se describen en un documento
separado, 
@iftex
el Manual de referencia de funcionamiento interno.
@end iftex
@ifnottex
la @ref{Top,Referencia de funcionamiento interno,,lilypond-internals}.
@end ifnottex
Dicho manual
relaciona todas las variables, funciones y opciones que se encuentran disponibles en
LilyPond.  Está escrito como un documento HTML, que se puede encontrar en
@c leave the @uref as one long line.
@uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/user/@/lilypond@/-internals/,on@/-line},
pero que también va incluido en el paquete de la documentación de LilyPond.

Hay cuatro áreas en las que se pueden cambiar los valores por defecto:

@itemize
@item
Notación automática: cambiar la creación automática de los elementos de
notación.  Por ejemplo, cambiar las reglas de barrado de las figuras.

@item
Salida: cambiar el aspecto de los objetos individuales.
Por ejemplo, cambiar las direcciones de las plicas o la situación exacta de
los subíndices.

@item
Contexto: modificar aspectos de la traducción de los eventos musicales en
notación.  Por ejemplo, dar a cada pentagrama una indicación de compás distinta.

@item
Disposición de la página: cambiar el aspecto visual del espaciado, los saltos de
línea y las dimensiones de la página.  Estas modificaciones se discuten
en @ref{Non-musical notation} y @ref{Spacing issues}.
@end itemize

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


@menu
* Interpretation contexts::     
* The \override command::       
@end menu


@node Interpretation contexts
@section Interpretation contexts

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

@menu
* Contexts explained::          
* Creating contexts::           
* Changing context properties on the fly::  
* Modifying context plug-ins::  
* Layout tunings within contexts::  
* Changing context default settings::  
* Defining new contexts::       
* Aligning contexts::           
* Vertical grouping of grobs::  
@end menu


@node Contexts explained
@subsection Contexts explained

Cuando se imprime la música, se tienen que añadir a la salida una gran cantidad de elementos
notacionales.  Por ejemplo, compare la entrada y la salida del siguiente ejemplo:

@lilypond[quote,verbatim,relative=2,fragment]
cis4 cis2. g4
@end lilypond

La entrada es bastante escueta, pero en la salida se añaden líneas divisorias, alteraciones accidentales,
la clave y la indicación de compás.  LilyPond @emph{interpreta} la
entrada.  En esta fase se inspecciona la información musical en orden temporal,
de forma parecida a la lectura de una partitura de izquierda a derecha. Mientras se lee
la entrada, el programa recuerda dónde se encuentran los límites de los compases, y qué notas
requieren alteraciones explícitas.  Esta información se puede presentar sobre varios
niveles.  Por ejemplo, el efecto de una alteración accidental se encuentra limitada
a un solo pentagrama, mientras que una barra divisoria debe estar sincronizada a través
de la partitura de arriba a abajo.

Dentro de LilyPond, estas reglas y pequeñas porciones de información se agrupan en
@emph{Contexts}.  Algunos ejemplos de contextos son @code{Voice} (Voz),
@code{Staff} (Pauta o pentagrama) y @code{Score} (Partitura).  Los contextos son jerárquicos, por
ejemplo: un @code{Staff} contener muchas @code{Voice}s, y una
@code{Score} puede contener muchos contextos de @code{Staff}.

@quotation
@sourceimage{context-example,5cm,,}
@end quotation

Cada contexto asume la responsabilidad de imponer algunas reglas de notación,
creando ciertos objetos de notación y manteniendo las propiedades
asociadas.  Por ejemplo, el contexto @code{Voice} puede introducir una alteración
accidental y entonces el contexto @code{Staff} mantiene la regla de mostrar o
suprimir la alteración para el resto del compás.  La
sincronización de las líneas divisorias se gestiona dentro del contexto de la partitura, @code{Score}.

Sin embargo, en algunas músicas posiblemente no queramos que las líneas divisorias estén
sincronizada (pensemos en una partitura polimétrica en compases de 4/4 y de 3/4).  En tales casos,
debemos modificar los ajustes por omisión de los contextos @code{Score}
y @code{Staff}.

Para partituras muy sencillas, los contextos se crean implícitamente y no debemos
preocuparnos por ellos.  Para piezas mayores, como por ejemplo cualquiera que tenga más de un pentagrama,
los contextos se deben crear explícitamente para asegurarnos
de que tendremos la cantidad exacta de pentagramas que necesitamos,
y que están en el orden correcto.  Para tipografiar piezas
con notación especializada, puede ser útil modificar contextos existentes
o definir unos nuevos.


En la referencia del programa se encuentra una descripción completa de todos los contextos que están disponibles,
consulte
@ifhtml
@rinternals{Contexts}.
@end ifhtml
@ifnothtml
Traducción @expansion{} Contexto.
@end ifnothtml

@c [TODO: describe propagation]


@node Creating contexts
@subsection Creating contexts

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

@itemize

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

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

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

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

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

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

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

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


@funindex \context

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

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

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

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

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

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

@noindent

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

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

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

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

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

@cindex crear contextos

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


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

Esta variante se usa con expresiones musicales que se pueden interpretar en
varios niveles.  Por ejemplo, la instrucción @code{\applyOutput} (véase
@ref{Running a function on all layout objects}).  Sin una instrucción
@code{\context} explícita, normalmente se aplicaría a @code{Voice}

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

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

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

@end itemize


@node Changing context properties on the fly
@subsection Changing context properties on the fly

@cindex properties
@funindex \set
@cindex changing properties

Cada contexto puede tener diferentes @emph{propiedades} o variables contenidas
en dicho contexto.  Se pueden cambiar mientras se desarrolla la fase de interpretación.
Esto se consigue insertando la instrucción @code{\set} en la música,

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

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

Esta instrucción hace que se salten los compases que no tienen ninguna nota.  El resultado es que
los silencios multicompás se comprimen.  El valor asignado es un objeto del lenguaje Scheme.  En
este caso, es @code{#t}, el valor booleano Verdadero.

Si el argumento @var{contexto} se deja en blanco, entonces se utiliza el contexto actual más bajo
(normalmente @code{ChordNames}, @code{Voice} o
@code{Lyrics}).  En este ejemplo,

@lilypond[quote,verbatim,relative=2,fragment]
c8 c c c
\set autoBeaming = ##f
c8 c c c
@end lilypond

@noindent
el argumento @var{contexto} para la instrucción @code{\set} está omitido, por tanto
el barrado automático está desactivado en la @rinternals{Voice} (voz) actual.  Fíjese en que
el contexto más bajo no siempre contiene la propiedad que quiere
cambiar. Por ejemplo, si intenta establecer la propiedad @code{skipBars}
(del contexto más bajo, en este caso @code{Voice}) no se producirá ningún
efecto.

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

Los contextos son jerárquicos, de forma que si se especificó un contexto mayor, por
ejemplo @code{Staff}, entonces el cambio también se aplicaría a todos los
@code{Voice}s o contextos de voz en el pentagrama actual.  El cambio se aplica
@q{al vuelo}, mientras transcurre la música, de manera que el ajuste sólo afecta al segundo
grupo de corcheas.

@funindex \unset

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

@noindent
que quita la definición de la @var{propiedad}.  Esta instrucción quita
la definición solamente si está establecida dentro del @var{contexto} especificado, por lo que

@example
\set Staff.autoBeaming = ##f
@end example

@noindent
introduce un ajuste de propiedad en el nivel del contexto @code{Staff}.  El ajuste también se aplica
a la @code{Voice} actual.  Sin embargo,

@example
\unset Voice.autoBeaming
@end example

@noindent
no tiene ningún efecto.  Para cancelar este ajuste, el @code{\unset}
se debe especificar en el mismo nivel que el @code{\set} original.  En
otras palabras, deshacer el efecto de @code{Staff.autoBeaming = ##f}
requiere
@example
\unset Staff.autoBeaming
@end example

Igual que @code{\set}, el argumento @var{contexto} no tiene que especificarse para un contexto
que está en la parte más baja, por lo que las dos instrucciones

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

@noindent
son equivalentes.


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

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

la propiedad @code{fontSize} pierde su valor automáticamente después de la segunda
nota.

En la referencia del programa hay una descripción detallada de todas las propiedades de contexto disponibles,
véase
@ifhtml
@rinternals{Tunable context properties}.
@end ifhtml
@ifnothtml
Traducción @expansion{} propiedades de contexto ajustables.
@end ifnothtml


@node Modifying context plug-ins
@subsection Modifying context plug-ins

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

Para ver una descripción completa de cada uno de los añadidos, consulte
@ifhtml
@rinternals{Engravers}.
@end ifhtml
@ifnothtml
Referencia del programa @expansion Traducción @expansion{} Grabadores.
@end ifnothtml
cada uno de los contextos descritos en
@ifhtml
@rinternals{Contexts}
@end ifhtml
@ifnothtml
Referencia del programa @expansion Traducción @expansion{} Contexto.
@end ifnothtml
relaciona los grabadores utilizados para ese contexto.


Puede ser útil poner o quitar estos añadidos.  Esto se hace
iniciando un contexto nuevo con @code{\new} o @code{\context} y
modificándolo,

@funindex \with

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

@noindent
donde los @dots{} serían el nombre de un grabador.  A continuación se presenta un ejemplo sencillo
que quita los grabadores @code{Time_signature_engraver} y
@code{Clef_engraver} de un contexto @code{Staff},

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

En el segundo pentagrama no hay indicación de compás ni clave.  Ésta es
una forma un poco fuerte de hacer desaparecer objetos, porque afectará
al pentagrama completo.  Este método también influye en el espaciado, lo que podría ser
deseable o no.  Un método más
sofisticado de borrar objetos se muestra en @rlearning{Further tweaking}.

El ejemplo siguiente muestra una aplicación práctica.  Las líneas divisorias y las indicaciones
de compás están normalmente sincronizadas en toda la partitura.  Esto se hace
por parte del @code{Timing_translator} y el grabador @code{Default_bar_line_engraver}.
Este añadido mantiene al día la administración de la indicación de compás, colocación
dentro del compás, etc.  Moviendo el grabador desde el contexto @code{Score} al
contexto @code{Staff}, podemos tener una partitura donde cada pentagrama tiene su propia
indicación de compás.

@cindex polimétricas, partituras
@cindex Indicaciones de compás, varias

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


@node Layout tunings within contexts
@subsection Layout tunings within contexts

Cada contexto es responsable de crear ciertos tipos de objetos
gráficos.  Los ajustes utilizados para imprimir estos objetos también se almacenan en cada contexto.
Cambiando estos ajustes se puede alterar la apariencia visual de los
objetos.

La sintaxis de esto es

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

Aquí @var{nombre} es el nombre de un objeto gráfico, como @code{Stem} (plica) o
@code{NoteHead} (cabeza de nota), y @var{propiedad} es una variable interna del sistema
de formateo (@q{propiedad del objeto gráfico o grob} o @q{propiedad de la disposición o layout}).  El último es un
símbolo, por ello debe ir entre comillas.  La subsección @ref{Constructing a
tweak} explica qué datos hay que cumplimentar para las variables @var{nombre}, @var{propiedad} y
@var{valor}.  Aquí discutiremos solamente la funcionalidad de esta instrucción.

La instrucción

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

@noindent
hace las plicas más gruesas (el valor por defecto es 1.3, tomando como unidad el grosor de las líneas del
pentagrama).  Puesto que la orden especifica @code{Staff} como contexto, sólo se
aplica al pentagrama en curso.  Otros pentagramas conservarán su apariencia visual
normal.  Aquí podemos ver la orden en acción:

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

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

Análogo a @code{\set}, el argumento @var{contexto} se puede dejar en blanco,
haciendo que se utilice el contexto por defecto, @code{Voice}.  Al añadir
@code{\once} se aplicará el cambio solamente durante un paso de tiempo.

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

El @code{\override} debe hacerse antes de que el objeto haya
comenzado.  Por ello, al alterar objetos de extensión o @emph{Spanner} tales como ligaduras
o barras de figuras, la instrucción @code{\override} debe ejecutarse en el momento en que se
crea el objeto.  En este ejemplo,

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

@noindent
la ligadura es más gruesa, no así la barra.  Esto es así porque la orden para la barra
@code{Beam} va después de que la barra Beam ha comenzado, así que no tiene ningún efecto.

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

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

Algunas opciones trucables reciben el nombre de @q{subpropiedades} y residen dentro de las
propiedades.  Para trucarlas, utilice órdenes de la forma

@c leave this as a long long
@example
\override @var{contexto}.@var{nombre} #'@var{propiedad} #'@var{subpropiedad} = #@var{valor}
@end example

@noindent
tal y como

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


@seealso

Funcionamiento interno: @rinternals{OverrideProperty}, @rinternals{RevertProperty},
@rinternals{PropertySet}, @rinternals{Backend} y
@rinternals{All layout objects}.


@knownissues

El back-end o parte profunda del programa no es muy estricta cuando se trata de la comprobación de tipos de las propiedades de los objetos.
Las referencias circulares en los valores de Scheme para las propiedades pueden causar cuelgues o
terminaciones abruptas, o las dos cosas.


@node Changing context default settings
@subsection Changing context default settings

Los ajustes de las subsecciones previas (@ref{Changing context
properties on the fly}, @ref{Modifying context plug-ins} y
@ref{Layout tunings within contexts}) también se pueden escribir separados de la  música
dentro del bloque @code{\layout},

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

    \set fontSize = #-2
    \override Stem #'thickness = #4.0
    \remove "Time_signature_engraver"
  @}
@}
@end example

La orden @code{\Staff} saca la definición existente del contexto de
pentagrama de manera que pueda ser modificada.

Las instrucciones
@example
\set fontSize = #-2
\override Stem #'thickness = #4.0
\remove "Time_signature_engraver"
@end example

@noindent
afectan a todos los pentagramas de la partitura.  Otros contextos se pueden modificar de forma
análoga.

La palabra clave @code{\set} es opcional dentro del bloque @code{\layout}, y así:

@example
\context @{
  @dots{}
  fontSize = #-2
@}
@end example

@noindent
también funciona.



@knownissues

No es posible recolectar cambios de contexto en una variable y aplicarlos
a una definición @code{\context} mediante la referencia a esa variable.

El @code{\RemoveEmptyStaffContext} sobreescribirá sus ajustes actuales
de @code{\Staff}.  Si quiere cambiar los valores por defecto para un pentagrama que usa
@code{\RemoveEmptyStaffContext}, tendrá que hacerlo después de
llamar a @code{\RemoveemptyStaffContext}, es decir

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

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


@node Defining new contexts
@subsection Defining new contexts

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

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

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

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


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

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

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

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

@example
\name ImproVoice
@end example

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

@example
\alias Voice
@end example

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

@example
\consists Note_heads_engraver
\consists Text_engraver
@end example

Pero sólo necesitamos esto en la línea central,

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

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

Las notas parecen barras inclinadas y no tienen plica,

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

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

@example
\type "Engraver_group"
@end example

Al juntarlo todo, obtenemos

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

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

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

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

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

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

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

@example
\relative c'' @{
  a4 d8 bes8
  \new ImproVoice @{
    c4^"ad lib" c
    c4 c^"undress"
    c c_"while playing :)"
  @}
  a1
@}
@end example


@node Aligning contexts
@subsection Aligning contexts

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

ARREGLAR: esta sección no funciona en PDF. (¿?)

@cindex ossia
@findex alignAboveContext
@findex alignBelowContext

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


@node Vertical grouping of grobs
@subsection Vertical grouping of grobs

Los grobs (objetos gráficos) VerticalAlignment y VerticalAxisGroup funcionan juntos.
VerticalAxisGroup agrupa distintos objetos gráficos como Staff, Lyrics,
etc.  VerticalAlignment por su parte alinea verticalmente los diferentes objetos gráficos
agrupados por VerticalAxisGroup.  Normalmente hay solamente un
VerticalAlignment por cada partitura, pero cada Staff, Lyrics, etc. tiene su propio
VerticalAxisGroup. 


@node The \override command
@section The @code{\override} command

En la sección anterior ya hemos tocado una orden que
modifica los detalles de la presentación: la instrucción @code{\override}.  En esta sección
observaremos con mayor detalle la manera de usar esta orden en la práctica.  La
sintaxis general de esta orden es:

@example
\override @var{contexto}.@var{objeto_de_presentación} #'@var{propiedad_de_presentación} = #@var{valor}
@end example

Así establecemos la @var{propiedad_de_presentación} del @var{objeto_de_presentación} especificado,
que es miembro del @var{contexto}, al @var{valor} que se indica.

@menu
* Constructing a tweak::        
* Navigating the program reference::  
* Layout interfaces::           
* Determining the grob property::  
* Objects connected to the input::  
* Using Scheme code instead of \tweak::  
* \set versus \override::       
* Difficult tweaks::            
@end menu



@node Constructing a tweak
@subsection Constructing a tweak

Las instrucciones que cambian la salida generalmente tienen la forma

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

@noindent
Para construir este ajuste debemos primero averiguar estos datos:

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

Ciertas opciones ajustables se llaman @q{subpropiedades} y residen en el interior
de las propiedades.  Para trucarlas, utilice órdenes de la forma

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

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

Para muchas propiedades, independientemente del tipo de datos de la propiedad, el establecimiento del valor de la
propiedad a Falso ( @code{##f} ) dará como resultado su apagado o desactivación, haciendo que
Lilypond ignore por completo dicha propiedad.  Esto es especialmente útil para
desactivar propiedades de objetos gráficos que, de otro modo, podrían causar problemas.

Explicaremos a continuación cómo extraer esta información del manual de notación y de la
referencia del programa.




@node Navigating the program reference
@subsection Navigating the program reference

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

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

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

@quotation
@seealso

Referencia de funcionamiento interno: @rinternals{Fingering}.

@end quotation


@c  outdated info; probably will delete.
@ignore
This fragment points to two parts of the program reference: a page
on @code{FingerEvent} and one on @code{Fingering}.

The page on @code{FingerEvent} describes the properties of the music
expression for the input @code{-2}.  The page contains many links
forward.  For example, it says

@quotation
Accepted by: @rinternals{Fingering_engraver},
@end quotation

@noindent
That link brings us to the documentation for the Engraver, the
plug-in, which says

@quotation
This engraver creates the following layout objects: @rinternals{Fingering}.
@end quotation
In other words, once the @code{FingerEvent}s are interpreted, the
@code{Fingering_engraver} plug-in will process them.
@end ignore

@ignore
@c  I can't figure out what this is supposed to mean.  -gp

The @code{Fingering_engraver} is also listed to create
@rinternals{Fingering} objects,

@c  old info?  it doesn't make any sense to me with our current docs.
This is also the
second bit of information listed under @b{See also} in the Notation
manual.
@end ignore

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

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

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

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

@itemize

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

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

@item @rinternals{fingering-event}:
El tipo de evento musical @code{fingering-event} está descrito en Expresiones musicales con el nombre de
@rinternals{FingerEvent}
@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
@subsection Layout interfaces

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

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

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

@quotation
@code{relleno} (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
@ref{File structure})
@file{scm/@/define@/-grobs@/.scm} muestra el alma del @q{objeto},

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

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


@node Determining the grob property
@subsection Determining the grob property

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

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

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

@quotation
@code{side-position-interface}

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

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

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

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

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

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

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


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

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


@node Objects connected to the input
@subsection Objects connected to the input

@funindex \tweak

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

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

Como podemos ver, las propiedades se establecen directamente dentro de los objetos,
sin hacer mención al nombre del grob ni al contexto en el que se tendría que
aplicar.

Esta técnica sólo funciona para los objetos que están conectados directamente a
un @rinternals{Event} (evento) del texto de entrada, por ejemplo

@itemize
@item cabezas de nota, producidas por chord-pitch (p. ej.: las notas de un acorde)
@item signos de articulación, producidos por instrucciones de articulación
@end itemize

Posiblemente no funcione para plicas y alteraciones accidentales (éstos están producidos
por parte de las cabezas de nota, no por los eventos musicales) ni para las claves (éstos no están producidos por
ninguna entrada musical, sino más bien a causa de un cambio en el valor de una propiedad).

Existen muy pocos objetos que estén conectados @emph{directamente} al
resultado de salida.  Una nota normal (como @code{c4}) no está conectada directamente
a la salida, así que

@example
\tweak #'color #red c4
@end example

@noindent
no cambia el color.  Consulte @ref{Displaying music expressions} para ver más
detalles.


@node Using Scheme code instead of \tweak
@subsection Using Scheme code instead of @code{\tweak}

La principal desventaja de @code{\tweak} es su inflexibilidad
sintáctica.  Por ejemplo, lo siguiente produce un error de sintaxis.

@example
F = \tweak #'font-size #-3 -\flageolet

\relative c'' @{
  c4^\F c4_\F
@}
@end example

@noindent
En otras palabras, @code{\tweak} no se comporta como una articulación en lo que respecta a la
sintaxis; en concreto, no se puede adjuntar mediante
@code{^} y @code{_}.

Utilizando el lenguaje Scheme, se puede dar un rodeo a este problema.  La ruta hacia el resultado
se da en @ref{Adding articulation to notes (example)},
especialmente cómo usar @code{\displayMusic} como guía de ayuda.

@example
F = #(let ((m (make-music 'ArticulationEvent
                          'articulation-type "flageolet")))
       (set! (ly:music-property m 'tweaks)
             (acons 'font-size -3
                    (ly:music-property m 'tweaks)))
       m)
 
\relative c'' @{
  c4^\F c4_\F
@}
@end example

@noindent
Aquí las propiedades @code{tweaks} del objeto de flageolet
@code{m} (creado con @code{make-music}) se extraen con
@code{ly:music-property}, un nuevo par clave-valor para cambiar el
tamaño de la tipografía se antepone a la lista de propiedades con la función de Scheme
@code{acons}, y el resultado finalmente se escribe
de nuevo con @code{set!}.  El último elemento del bloque
@code{let} es el valor devuelto, el propio @code{m}.


@node \set versus \override
@subsection @code{\set} vs. @code{\override}

Hemos visto dos formas de cambiar las propiedades: @code{\set} y
@code{\override}.  De hecho, en realidad existen dos clases diferentes de
propiedades.

Los contextos pueden tener propiedades, que por lo general reciben nombres en
@code{mayúsculasDeCamello}.  Principalmente controlan la traducción
de la música a la notación, p.ej. @code{localKeySignature} (para determinar
si hay que imprimir las alteraciones accidentales), @code{measurePosition} (para
determinar cuándo imprimir una línea divisoria).  Las propiedades de contexto pueden
ver modificado su valor con el tiempo según se interpreta una pieza de música;
@code{measurePosition} es un ejemplo obvio de esto.
Las propiedades de contexto se modifican con @code{\set}.

Hay un tipo especial de propiedad de contexto: la descripción del
elemento.  Estas propiedades reciben nombres en @code{MayúsculasDeCamello}
(comenzando en letra mayúscula).  Contienen los
@q{ajustes por defecto} para dicho elemento gráfico como una lista
asociativa.  Consulte @file{scm/@/define@/-grobs@/.scm}
para ver qué tipos de ajustes hay.  Las descripciones de los elementos
se pueden modificar con @code{\override}.

Realmente, @code{\override} es un atajo;

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

@noindent
es más o menos equivalente a

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

El valor de @code{contexto} (la lista-a) se usa para da un valor inicial
a las propiedades de los objetos gráficos individuales.  Los objetos gráficos también tienen
propiedades, que reciben nombres en el estilo de Scheme, con
@code{palabras-con-guiones}.  Los valores de las propiedades de objetos gráficos cambian
durante el proceso de formateo: el formateo básicamente consiste en
calcular las propiedades utilizando funciones de callback.

@code{fontSize} es una propiedad especial: equivale a
escribir @code{\override ... #'font-size} para todos los objetos
pertinentes.  Al ser éste un cambio muy común, se creó la propiedad especial
(modificada con @code{\set}).


@node Difficult tweaks
@subsection Difficult tweaks

Hay ciertos tipos de ajustes difíciles.

@itemize


@item
Un tipo de ajuste difícil es la apariencia visual de los objetos de extensión,
como las ligaduras de expresión y de unión.  Inicialmente sólo se crea uno de estos objetos,
y se pueden ajustar a través del mecanismo normal.  Sin embargo, en ocasiones
los objetos de extensión atraviesan los saltos de línea.  Si esto ocurre, estos objetos
se clonan.  Se crea un objeto separado para cada grupo de pentagramas en el que está.
Son clones del objeto original y heredan todas las
propiedades, incluyendo los @code{\override}s.


En otras palabras, un @code{\override} siempre afecta a todas las piezas de un elemento de
extensión roto.  Para cambiar sólo una parte del elemento de extensión  en un salto de línea,
es necesario implicarse en el proceso de formateo.  La función de callback
@code{after-line-breaking} contiene el procedimiento de Scheme que
se llama después de que se han determinado los saltos de línea, y de que los objetos de
presentación se han dividido sobre los diferentes sistemas o grupos de pentagramas.

En el ejemplo siguiente, definimos un procedimiento
@code{my-callback}.  Este procedimiento

@itemize
@item
determina si hemos sido divididos en un salto de línea
@item
si es así, recupera todos los objetos divididos
@item
comprueba si nosotros somos el último de los objetos divididos
@item
si es así, establece @code{extra-offset}.
@end itemize

Este procedimiento se instala dentro de @rinternals{Tie} (ligadura de unión), de forma que la última parte
de la ligadura dividida se traslada hacia arriba.

@c KEEP LY
@lilypond[quote,verbatim,ragged-right]
#(define (my-callback grob)
  (let* (
         ; ¿el objeto se ha dividido?
         (orig (ly:grob-original grob))

         ; si es así, tomar las piezas divididas (siblings)
         (siblings (if (ly:grob? orig)
                     (ly:spanner-broken-into orig) '() )))

   (if (and (>= (length siblings) 2)
             (eq? (car (last-pair siblings)) grob))
     (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))

\relative c'' {
  \override Tie #'after-line-breaking =
  #my-callback
  c1 ~ \break c2 ~ c
}
@end lilypond

@noindent
Cuando aplicamos este truco, la nueva función de callback @code{after-line-breaking}
también debe llamar a la antigua @code{after-line-breaking}, si existe.
Por ejemplo, si se utiliza con @code{Hairpin} (regulador),
también se debe llamar a @code{ly:hairpin::after-line-breaking}.


@item Algunos objetos no se pueden cambiar con @code{\override} por razones
técnicas.  Ejemplo de ello son @code{NonMusicalPaperColumn}
y @code{PaperColumn}.  Se pueden cambiar con la función
@code{\overrideProperty}, que funciona de forma parecida a @code{\once
\override}, pero usa una sintaxis diferente.

@example
\overrideProperty
#"Score.NonMusicalPaperColumn"  % Nombre del Grob u objeto gráfico
#'line-break-system-details     % Nombre de la propiedad
#'((next-padding . 20))         % Valor
@end example

Fíjese, sin embargo, en que @code{\override}, aplicado a
@code{NoteMusicalPaperColumn} y a @code{PaperColumn}, aún funciona tal y como se espera
dentro de los bloques @code{\context}.

@end itemize