From: Francisco Vila <francisco.vila@hispalinux.es>
Date: Wed, 19 Mar 2008 16:44:21 +0000 (+0100)
Subject: Modifying context properties, complete rewrite
X-Git-Tag: release/2.11.43-1~26^2^2
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=8a5b4b64ac3bc417ad9b7f7fbe53baa73d620fdc;p=lilypond.git

Modifying context properties, complete rewrite
---

diff --git a/Documentation/es/user/fundamental.itely b/Documentation/es/user/fundamental.itely
index e041761937..f5f1d33d73 100644
--- a/Documentation/es/user/fundamental.itely
+++ b/Documentation/es/user/fundamental.itely
@@ -697,125 +697,226 @@ mediante la modificación del funcionamiento de los Grabadores.
 @node Modifying context properties
 @subsection Modifying context properties
 
-@cindex properties
+@cindex contexto, propiedades de
 @funindex \set
-@cindex changing properties
+@funindex \unset
 
-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,
+Los contextos se responsabilizan de mantener los valores de un cierto
+número de @emph{properties} de contexto.  Muchas de ellas se pueden
+cambiar para influir en la interpretación del código de entrada y
+cambiar así la apariencia de la salida impresa.  Se modifican mediante
+la instrucción @code{\set}.  Esta instrucción toma la forma siguiente:
 
 @example
-\set @var{contexto}.@var{propiedad} = #@var{valor}
+\set @emph{NombreDelContexto}.@emph{nombreDeLaPropiedad} = #@emph{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.
+Donde el @emph{NombreDelContexto} es normalmente @code{Score},
+@code{Staff} o @code{Voice}.  Se puede omitir, en cuyo caso se supone
+que es @code{Voice}.
 
-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,
+Los nombres de las propiedades de contexto consisten en palabras
+unidas sin ningún guión o barra baja, y donde todas las palabras
+excepto la primera empiezan en mayúscula.  A continuación podemos ver
+algunos ejemplos de nombres de propiedades utilizadas con frecuencia.
+Hay muchas más que las que se muestran aquí.
 
-@lilypond[quote,verbatim,relative=2,fragment]
-c8 c c c
-\set autoBeaming = ##f
-c8 c c c
-@end lilypond
+@c attempt to force this onto a new page
+@need 50
+@multitable @columnfractions .25 .15 .45 .15
+@headitem nombreDeLaPropiedad
+  @tab Tipo
+  @tab Función
+  @tab Valor de ejemplo
+@item extraNatural
+  @tab Booleano
+  @tab Se es verdadero, poner becuadros adicionales antes de las alteraciones
+  @tab @code{#t}, @code{#f}
+@item currentBarNumber
+  @tab Entero
+  @tab Ajustar el número del compás actual
+  @tab @code{50}
+@item doubleSlurs
+  @tab Booleano
+  @tab Si es verdadero, imprimir ligaduras de expresión por encima y por debajo de las notas
+  @tab @code{#t}, @code{#f}
+@item instrumentName
+  @tab Texto
+  @tab Establecer el nombre del pentagrama, situado a la izquierda
+  @tab @code{"Cello I"}
+@item fontSize
+  @tab Real
+  @tab Aumentar o disminuir el tamaño de la fuente tipográfica
+  @tab @code{2.4}
+@item stanza
+  @tab Texto
+  @tab Establecer el texto que se imprime antes del comienzo de una estrofa
+  @tab @code{"2"}
+@end multitable
 
 @noindent
-el argumento @var{contexto} para la instrucción @code{\set} está omitido, por tanto
-el barrado automático está desactivado en la @internalsref{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.
+donde un valor Booleano es verdadero (@code{#t}, True) o falso
+(@code{#f}, False), un Entero es un número entero positivo, un número
+Real es un número decimal positivo o negativo, y el texto se encierra
+entre comillas dobles.  Observe la aparición de signos de cuadradillo,
+(@code{#}), en dos lugares diferentes: como parte del valor Booleano
+antes de la @code{t} o la @code{f}, y antes del @emph{valor} dentro de
+la sentencia @code{\set}.  Así pues, cuando se está escribiendo un
+valor Booleano, hay que escribir dos signos de cuadradillo, por
+ejemplo: @code{##t}.
+
+Antes de poder establecer cualquiera de estas propiedades, tenemos que
+saber en qué contexto operan.  A veces es algo obvio, pero en
+ocasiones puede ser algo enrevesado.  Si especificamos un contexto
+equivocado, no se produce ningún mensaje de error, pero el
+funcionamiento esperado no tendrá lugar.  Por ejemplo, la propiedad
+@code{instrumentName} (nombre del instrumento) vive claramente dentro
+del contexto de Staff, puesto que es el pentagrama el que debe ser
+nombrado.  En este ejemplo, el primer pentagrama resulta etiquetado,
+pero no el segundo, porque hemos omitido el nombre del contexto.
 
-@lilypond[quote,verbatim,relative=2,fragment]
-R1*2
-\set skipBars = ##t
-R1*2
+@lilypond[quote,verbatim,ragged-right]
+<<
+  \new Staff \relative c'' {
+    \set Staff.instrumentName = #"Soprano"
+    c4 c
+ }
+  \new Staff \relative c' {
+  \set instrumentName = #"Alto"  % Wrong!
+  d4 d 
+ }
+>>
 @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
+Recuerde que el nombre del contexto predeterminado es Voice, así que
+la segunda instrucción @code{\set} establece la propiedad
+@code{instrumentName} del contexto Voice a @qq{Alto}, pero como
+LilyPond no busca esta propiedad en el contexto @code{Voice}, no se
+realiza ninguna acción.  Esto no es un error, y no se registra ningún
+mensaje en el archivo de errores Log.
+
+De forma parecida, si el nombre de la propiedad se escribe con alguna
+falta, no se produce ningún mensaje de error, y claramente la acción
+esperada no puede tener lugar.  De hecho, se puede establecer
+cualquier @q{property} (ficticia) usando cualquier nombre que queramos
+en cualquier contexto que exista, mediante el uso de la instrucción
+@code{\set}.  Pero si el nombre no es conocido para LilyPond, no
+producirá ninguna acción.  Esta es una de las razones por las que es
+muy recomendable ussar un editor que sea sensible al contexto y con
+resaltado de la sintaxis para la edición de archivos de LilyPond, como
+por ejemplo Vim, Jedit, ConTEXT o Emacs, ya que los nombres de
+propiedades desconocidas se resaltarán de forma distinta.
+
+La propiedad @code{instrumentName} tendrá efecto solamente si se
+establece dentro del contexto @code{Staff}, pero algunas propiedades
+se pueden establecer en más de un contexto.  Por ejemplo, la propiedad
+@code{extraNatural} está establecida por defecto al valor ##t
+(verdadero) para todos los pentagramas.  Si se establece a ##f (falso)
+en un contexto de @code{Staff} determinado, se aplicará solamente a
+las alteraciones de ese pentagrama.  Si se establece a falso en el
+contexto de la partitura, @code{Score}, se aplicará a todos los
+pentagramas.
+
+Así, esto desactivará los becuadros adicionales en un pentagrama:
 
-También existe una instrucción @code{\unset},
-@example
-\unset @var{contexto}.@var{propiedad}
-@end example
+@lilypond[quote,verbatim,ragged-right]
+<<
+  \new Staff \relative c'' {
+    ais4 aes
+ }
+  \new Staff \relative c'' {
+    \set Staff.extraNatural = ##f
+    ais4 aes
+ }
+>>
+@end lilypond
 
 @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
+y esto los desactivará en todos los pentagramas:
 
-@example
-\set Staff.autoBeaming = ##f
-@end example
+@lilypond[quote,verbatim,ragged-right]
+<<
+  \new Staff \relative c'' {
+    ais4 aes
+ }
+  \new Staff \relative c'' {
+    \set Score.extraNatural = ##f
+    ais4 aes
+ }
+>>
+@end lilypond
 
-@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,
+El valor de cada propiedad establecido de esta forma se puede devolver
+a su valor original con la instrucción @code{\unset}.
+ 
+Las instrucciones @code{\set} y @code{\unset} pueden aparecer en
+cualquier lugar del archivo de entrada y tendrán efecto a partir del
+tiempo en que se encuentran y hasta el final de la partitura o hasta
+que la propiedad se establezca de nuevo mediante @code{\set} o
+@code{\unset}.  Probemos a modificar el tamaño de la fuente
+tipográfica, lo que afecta al tamaño de las cabezas de las notas
+(entre otras cosas) varias veces.  El cambio se toma a partir del
+valor predeterminado, no el valor en curso.
+
+@lilypond[quote,verbatim,ragged-right,relative=1,fragment]
+c4 
+% make note heads smaller
+\set fontSize = #-4
+d e
+% make note heads larger
+\set fontSize = #2.5
+f g
+% return to original size
+\unset fontSize
+a b
+@end lilypond
 
-@example
-\unset Voice.autoBeaming
-@end example
+Hemos podido ver cómo establecer los valores de diversos tipos de
+propiedad diferentes.  Observe que los números enteros y reales van
+siempre precedidos de un símbolo de cuadradillo, @code{#}, mientras
+que un valor booleano verdadero o falso se especifica mediante ##t y
+##f, con dos cuadradillos.  Una propiedad de texto se debe encerrar
+entre comillas dobles, como antes, aunque veremos más adelante que el
+texto realmente se peude especificar de una dorma mucho más general
+utilizando la potentísima instrucción @code{markup}.
 
-@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
+@funindex \with
+
+Las propiedades de contexto también se pueden establecer en el momento
+en que se crea el contexto.  A veces esta forma de establecer el valor
+de una propiedad es mucho más clara, si ha de quedar fijo durante todo
+el tiempo que dure el contexto.  Cuando se crea un contexto con una
+instrucción @code{\new} puede ir inmediatamente seguido de un bloque
+@code{\with @{ .. @}} en el que se establecen los valores de las
+propiedades.  Por ejemplo, si queremos suprimir la impresión de
+becuadros adicionales para toda la duración de un pentagrama, podemos
+escribir:
 
 @example
-\set Voice.autoBeaming = ##t
-\set autoBeaming = ##t
+\new Staff \with @{ extraNatural = ##f @}
 @end example
 
 @noindent
-son equivalentes.
-
+de la siguiente forma:
 
-@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
+@lilypond[quote,verbatim,ragged-right]
+<<
+  \new Staff
+  \relative c'' {
+    gis ges aes ais
+  }
+  \new Staff \with { extraNatural = ##f }
+  \relative c'' {
+    gis ges aes ais
+  }
+>>
 @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
-@internalsref{Tunable context properties}.
-@end ifhtml
-@ifnothtml
-Traducción @expansion{} propiedades de contexto ajustables.
-@end ifnothtml
+Efectivamente, esto sobreescribe el valor predeterminado de la
+propiedad.  Aún se puede modificar dinámicamente utilizando
+@code{\set} y devolverlo a su (nuevo) valor predeterminado con
+@code{\unset}.
 
 @node Adding and removing engravers
 @subsection Adding and removing engravers