From: Francisco Vila <paconet.org@gmail.com>
Date: Fri, 12 Feb 2016 19:42:21 +0000 (+0100)
Subject: Preliminary sectioning: Tweaks.
X-Git-Tag: release/2.19.37-1~31
X-Git-Url: https://git.donarmstrong.com/lilypond.git?a=commitdiff_plain;h=c198dd2282cf4e4d87909271c961dcb326aefe39;p=lilypond.git

Preliminary sectioning: Tweaks.
---

diff --git a/Documentation/es/learning/tweaks.itely b/Documentation/es/learning/tweaks.itely
index cb6b875df4..02dcc3c6c6 100644
--- a/Documentation/es/learning/tweaks.itely
+++ b/Documentation/es/learning/tweaks.itely
@@ -113,6 +113,20 @@ propiedades relacionadas con su forma.  Los objetos con una forma
 extendida como estos, reciben el nombre de «Objetos de extensión» o
 @q{Spanners}.
 
+Spanners cannot be tweaked after their creation.  This includes both
+@code{StaffSymbol} and @code{LedgerLineSpanner} which continue
+throughout the score (except if they are terminated by the
+@code{\stopStaff} command and then recreated using @code{\startStaff}
+command.
+
+What is more, there are @q{abstract} grobs which do not print
+anything of their own, but rather collect, position and manage
+other grobs.  Common examples for this are
+@code{DynamicLineSpanner}, @code{BreakAlignment},
+@code{NoteColumn}, @code{VerticalAxisGroup},
+@code{NonMusicalPaperColumn} and similar.  We will see how some of
+these are used later.
+
 Aún falta por explicar qué son los @q{Interfaces}.  Muchos objetos,
 incluso aunque son bastante diferentes, comparten funcionalidades que
 se deben procesar de la misma manera.  Por ejemplo, todos los objetos
@@ -177,6 +191,11 @@ objeto se modifican por parte de diferentes instrucciones; así pues,
 es útil poder reconocer los tipos de objetos y propiedades
 a partir de sus nombres.
 
+@seealso
+Notation Reference:
+@ruser{Modifying properties}.
+
+
 @node Métodos de trucaje
 @subsection Métodos de trucaje
 @translationof Tweaking methods
@@ -321,9 +340,10 @@ dos últimas notas:
 @funindex \once
 @funindex once
 
-Tanto la instrucción @code{\override} como @code{\set} se pueden
-preceder por @code{\once}.  Esto ocasiona que la siguiente instrucción
-@code{\override} o @code{\set} sea efectiva solamente durante el
+@code{\override}, @code{\revert}. @code{\set}, and @code{\unset}
+se pueden
+preceder por @code{\once}.  Esto ocasiona que la instrucción
+sea efectiva solamente durante el
 tiempo musical en curso y antes de que la propiedad vuelva a tener
 otra vez su valor anterior (que puede ser distinto de su valor
 predeterminado si aún se está aplicando otra instrucción
@@ -340,8 +360,10 @@ podemos cambiar el color de una sola nota de la siguiente manera:
   e4 f |
   \once \override NoteHead.color = #green
   g4 a
-  \revert NoteHead.color
+  \once \revert NoteHead.color
   b c |
+  \revert NoteHead.color
+  f2 c |
 }
 @end lilypond
 
@@ -349,22 +371,17 @@ El prefijo @code{\once} también se puede usar delante de muchas
 instrucciones predefinidas para limitar su efecto a un solo momento
 musical:
 
-@lilypond[quote,verbatim,relative=1]
-c4 d
-\once \stemDown
-e4 f |
-g4 a
-\once \hideNotes
-b c |
+@lilypond[quote,verbatim]
+\relative {
+  c'4( d)
+  \once \slurDashed
+  e4( f) |
+  g4( a)
+  \once \hideNotes
+  b( c) |
+}
 @end lilypond
 
-Sin embargo, las instrucciones predefinidas de la forma
-@code{\@dots{}Neutral},
-@code{\@dots{}Off} y @code{\un@dots{}} utilizan
-internamente @code{\revert} en vez de @code{\override}, por lo que
-añadir @code{\once} como prefijo aquí no tiene ningún efecto.
-
-
 @node La instrucción overrideProperty
 @unnumberedsubsubsec La instrucción @code{@bs{}overrideProperty}
 @translationof The overrideProperty command
@@ -492,7 +509,8 @@ el evento original:
 Esta forma extensa de la instrucción @code{\tweak} se puede describir
 como
 @example
-\tweak @var{objeto-de-presentación}.@var{propiedad-de-presentación} @var{valor}
+\tweak @var{LayoutObject}.@var{layout-property} #@var{value}
+"ANTES" \tweak @var{objeto-de-presentación}.@var{propiedad-de-presentación} @var{valor}
 @end example
 
 @cindex grupos especiales anidados
@@ -560,6 +578,60 @@ se puede modificar de la forma usual mediante instrucciones
 Referencia de la notación:
 @ruser{La instrucción tweak}.
 
+@node The single prefix
+@unnumberedsubsubsec The @code{@bs{}single} prefix
+
+@funindex \single
+@cindex tweak, generated from override
+
+Suppose we wanted to emphasize particular note heads by coloring them
+red and increasing their size, and to make it easy suppose also we
+have defined a function to do this:
+
+@lilypond[quote,verbatim]
+emphNoteHead = {
+  \override NoteHead.color = #red
+  \override NoteHead.font-size = 2
+}
+\relative {
+  c''4 a \once \emphNoteHead f d |
+}
+@end lilypond
+
+The @code{\once} prefix works fine to emphasize single notes or
+complete chords, but it cannot be used to emphasize a single note
+@emph{within} a chord.  Earlier we have seen how @code{\tweak} can
+be used to do this, see
+@ref{The tweak command,,The @code{@bs{}tweak} command}.  But
+@code{\tweak} cannot be used with a function; that's where
+@code{\single} comes in:
+
+@lilypond[quote,verbatim]
+emphNoteHead = {
+  \override NoteHead.color = #red
+  \override NoteHead.font-size = 2
+}
+\relative {
+   <c'' a \single \emphNoteHead f d>4
+}
+@end lilypond
+
+In summary, @code{\single} converts overrides into tweaks so when
+there are several objects at the same point in musical time (like
+noteheads in a chord), @code{\single} will only affect a single one,
+the one generated by the immediately following music expression, in
+contrast to @code{\once} which will affect all of those objects.
+
+By using @code{\single} in this way any shorthand function
+containing just overrides may be applied to individual notes in a
+chord.  However, @code{\single} does not convert @code{\revert},
+@code{\set} or @code{\unset} into tweaks.
+
+@seealso
+Learning Manual:
+@ref{The tweak command,,The @code{@bs{}tweak} command},
+@ref{Using variables for layout adjustments}.
+
 
 @node Manual de referencia de funcionamiento interno
 @section Manual de referencia de funcionamiento interno
@@ -1933,32 +2005,31 @@ la propiedad @code{direction}.
 @cindex center
 @cindex neutral
 
-El ejemplo siguiente muestra en el compás 1 el comportamiento
-predeterminado de las plicas, con las de las notas agudas apuntando
-hacia abajo y las graves hacia arriba, seguidas de cuatro notas con
-todas las plicas forzadas hacia abajo, cuatro notas con las plicas
-forzadas hacia arriba, y por último cuatro notas devueltas al
-comportamiento predeterminado.
+The following example shows the default positioning of slurs in the
+first bar, with slurs starting on high notes positioned above the notes
+and those starting on low notes positioned below, followed by a bar
+with both slurs forced down, a bar with both slurs forced up, and
+finally a bar with both slurs reverted back to the default behavior.
 
-@cindex Stem, ejemplo de sobreescritura
+@cindex Slur, ejemplo de sobreescritura
 @cindex direction, propiedad, ejemplo
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-a4 g c a |
-\override Stem.direction = #DOWN
-a4 g c a |
-\override Stem.direction = #UP
-a4 g c a |
-\revert Stem.direction
-a4 g c a |
+@lilypond[quote,fragment,verbatim]
+a'4( g') c''( a') |
+\override Slur.direction = #DOWN
+a'4( g') c''( a') |
+\override Slur.direction = #UP
+a'4( g') c''( a') |
+\revert Slur.direction
+a'4( g') c''( a') |
 @end lilypond
 
-Aquí utilizamos las constantes @code{DOWN} (abajo) y @code{UP}
+Aquí hemos usado las constantes @code{DOWN} (abajo) y @code{UP}
 (arriba).  Éstos tienen los valores @w{@code{-1}} y @code{+1}
 respectivamente, y dichos valores numéricos también se pueden usar
 directamente.  El valor @code{0} también se puede usar en algunos
 casos.  Se trata simplemente con el significado de @code{UP} para las
-plicas, pero para algunos objetos tiene el significado de
+ligaduras de expresión, pero para algunos objetos tiene el significado de
 @q{centrado}.  Existe una constante @code{CENTER} que tiene el valor
 @code{0}.
 
@@ -2011,13 +2082,21 @@ menciona el significado de cada una allí donde no es obvio.
 @end multitable
 
 Las variantes neutras o normales de estas instrucciones están
-implementadas usando @code{\revert} y @strong{no} pueden ir
+implementadas usando @code{\revert} y éstas @strong{no} pueden ir
 precedidas de @code{\once}.  Si quiere limitar el efecto de las
 otras instrucciones (que están implementadas usando
 @code{\override}) a un solo paso de tiempo, puede precederla de
 @code{\once} de la misma forma en que lo haría con las
 sobreescrituras explícitas.
 
+Or, if just a single layout object needs to be forced up or down, the
+direction indicators, @code{^} or @code{_}, may be used:
+
+@lilypond[quote,fragment,verbatim]
+a'4( g') c''( a') |
+a'4^( g') c''_( a') |
+@end lilypond
+
 @node Digitaciones
 @unnumberedsubsubsec Digitaciones
 @translationof Fingering
@@ -3322,11 +3401,10 @@ a la izquierda, y 1.8 espacios de pentagrama hacia abajo:
 @cindex fingering (digitación), ejemplo de sobreescritura
 @cindex extra-offset, propiedad, ejemplo
 
-@lilypond[quote,fragment,relative=1,verbatim]
-\stemUp
-f4-5
+@lilypond[quote,fragment,verbatim]
+f'4-5
 \once \override Fingering.extra-offset = #'(-0.3 . -1.8)
-f4-5
+f'4-5
 @end lilypond
 
 
@@ -3381,18 +3459,26 @@ cuando se necesita.  Para aprender la manera de hacerlo, consulte
 Presentamos otro ejemplo.  Vemos que la barra
 choca con las ligaduras:
 
-@lilypond[quote,verbatim,fragment,ragged-right]
+@lilypond[quote,verbatim,ragged-right]
 {
   \time 4/2
   <<
-    { c'1 ~ 2. e'8 f' }
+    \relative { c'1~ 2. e8 f }
     \\
-    { e''8 e'' e'' e''  e'' e'' e'' e''  f''2 g'' }
+    \relative {
+      e''8 e e e
+      e e e e
+      f2 g
+    }
   >>
   <<
-    { c'1 ~ 2. e'8 f' }
+    \relative { c'1~ 2. e8 f }
     \\
-    { e''8 e'' e'' e''  e'' e'' e'' e''  f''2 g'' }
+    \relative {
+      e''8 e e e
+      e e e e
+      f2 g
+    }
   >>
 }
 @end lilypond
@@ -3405,29 +3491,37 @@ central hasta, digamos, 1 espacio:
 @cindex Beam, ejemplo de sobreescritura
 @cindex positions, propiedad, ejemplo
 
-@lilypond[quote,verbatim,fragment,ragged-right]
+@lilypond[quote,verbatim,ragged-right]
 {
   \time 4/2
   <<
-    { c'1 ~ 2. e'8 f' }
+    \relative { c'1~ 2. e8 f }
     \\
-    {
+    \relative {
       \override Beam.positions = #'(-1 . -1)
-      e''8 e'' e'' e''  e'' e'' e'' e''  f''2 g''
+      e''8 e e e
+      e e e e
+      f2 g
     }
   >>
   <<
-    { c'1 ~ 2. e'8 f' }
+    \relative { c'1~ 2. e8 f }
     \\
-    { e''8 e'' e'' e''  e'' e'' e'' e''  f''2 g'' }
+    \relative {
+      e''8 e e e
+      e e e e
+      f2 g
+      \revert Beam.positions
+    }
   >>
 }
 @end lilypond
 
 @noindent
-Observe que la sobreescritura sigue aplicándose en la primera voz del
+Observe que la sobreescritura sigue aplicándose en la segunda voz del
 segundo compás de corcheas, pero no a ninguna de las barras de la
-segunda voz.
+primera voz, ni siquiera a las que están en el in the later second measure.  As soon as the
+override should no longer apply it should be reverted, as shown.
 
 @node La propiedad force-hshift (forzar desplazamiento horizontal)
 @unnumberedsubsubsec La propiedad @code{force-hshift} (forzar desplazamiento horizontal)
@@ -3455,11 +3549,7 @@ dejamos con este aspecto:
 @noindent
 Es necesario que la nota interior del primer acorde (el La bemol
 de la cuarta voz) no se aparte de la columna vertical de la nota
-aguda.  Podríamos esperar corregirlo mediante el uso de
-@code{\shiftOff}, pero esto produce advertencias sobre columnas de
-notas que colisionan.  En lugar de ello, ajustamos a cero el valor
-para esta nota de @code{force-hshift}, que es una propiedad de
-@code{NoteColumn}.
+aguda, por lo que usamos @code{\shiftOff}.
 
 En el segundo acorde preferimos que el Fa esté alineado con el La
 bemol y que la nota grave se coloque ligeramente a la derecha para
@@ -3486,8 +3576,7 @@ Presentamos a continuación el resultado final:
     { <ees, c>2 \once \override NoteColumn.force-hshift = 0.5 des }
     \\
     \\
-    { \once \override NoteColumn.force-hshift = 0 aes'2
-      \once \override NoteColumn.force-hshift = 0 f4 fes }
+    { \once \shiftOff aes'2 \once \shiftOff f4 fes }
   >> |
   <c ees aes c>1 |
 }
@@ -3526,7 +3615,7 @@ rhMusic = \relative {
     \time 6/4
     \mergeDifferentlyHeadedOn
     \mergeDifferentlyDottedOn
-    bes2.^\markup { \bold "Moderato" } r8
+    bes2.\tempo "Moderato" r8
     <<
       { c,8 d fis bes a }
       \new Voice {
@@ -3783,9 +3872,8 @@ lhMusic = \relative {
 @end lilypond
 
 Vayamos ahora al tercer compás y comienzo de la sección Moderato.  El
-tutorial nos enseñó cómo escribir texto en negrita mediante la
-instrucción @code{\markup}, por lo que añadir @qq{Moderato} en negrita
-es fácil.  Pero ahora ¿cómo fundimos notas que están en distintas
+tutorial nos enseñó cómo escribir una indicación de tempo mediante la
+instrucción @code{\tempo}, por lo que añadir @qq{Moderato} es fácil.  Pero ahora ¿cómo fundimos notas que están en distintas
 voces?  Aquí es donde debemos volver a buscar ayuda en el manual de
 Referencia de la notación. Al buscar la palabra @qq{merge} (mezcla) en
 el índice de la Referencia de la notación llegamos rápidamente a las
@@ -3820,7 +3908,7 @@ rhMusic = \relative {
     bes1~ |
     \bar "||"
     \time 6/4
-    bes2.^\markup { \bold "Moderato" } r8
+    bes2.\tempo "Moderato" r8
     \mergeDifferentlyHeadedOn
     \mergeDifferentlyDottedOn
     % Start polyphonic section of four voices
@@ -3895,7 +3983,7 @@ rhMusic = \relative {
     bes1~ |
     \bar "||"
     \time 6/4
-    bes2.^\markup { \bold "Moderato" } r8
+    bes2.\tempo "Moderato" r8
     \mergeDifferentlyHeadedOn
     \mergeDifferentlyDottedOn
     % Start polyphonic section of four voices
@@ -3966,7 +4054,7 @@ rhMusic = \relative {
     bes1~ |
     \bar "||"
     \time 6/4
-    bes2.^\markup { \bold "Moderato" } r8
+    bes2.\tempo "Moderato" r8
     \mergeDifferentlyHeadedOn
     \mergeDifferentlyDottedOn
     % Start polyphonic section of four voices
@@ -4046,14 +4134,8 @@ lhMusic = \relative {
 * Simulación de un calderón en el MIDI::
 @end menu
 
-@cindex transparent, uso de la propiedad
-@cindex objetos, hace invisibles
 @cindex eliminar objetos
 @cindex objetos, eliminar
-@cindex objetos, ocultar
-@cindex ocultar objetos
-@cindex invisibles, objetos
-@cindex objetos invisibles
 
 @node Unir notas entre voces distintas
 @unnumberedsubsubsec Unir notas entre voces distintas
@@ -4063,7 +4145,7 @@ lhMusic = \relative {
 
 El ejemplo siguiente muestra cómo conectar notas que están en
 distintas voces utilizando ligaduras de unión.  Normalmente sólo se
-pueden conectar mediante ligaduras de unión dos notas que estén en la
+pueden conectar mediante ligaduras de unión notas que estén en la
 misma voz.  Usando dos voces, con las notas ligadas en una de ellas:
 
 @lilypond[quote]
@@ -4071,69 +4153,32 @@ misma voz.  Usando dos voces, con las notas ligadas en una de ellas:
 @end lilypond
 
 @noindent
-y borrando la primera plica hacia arriba en esa voz, da la impresión
+y borrando la primera plica (con su corchete) hacia arriba en esa voz, da la impresión
 de que la ligadura se cruza entre las voces:
 
-@cindex Stem, ejemplo de sobreescritura
-@cindex transparent, propiedad, ejemplo
-
-@lilypond[quote,fragment,relative=2,verbatim]
-<<
-  {
-    \tweak Stem.transparent ##t
-    b8~ 8\noBeam
-  }
-\\
-  { b8[ g] }
->>
-@end lilypond
-
-Para estar seguros de que la plica que acabamos de borrar no aprieta
-demasiado a la ligadura, podemos alargar la plica estableciendo su
-valor de longitud @code{length} a @code{8},
+@funindex \omit
+@cindex Stem, example of removing
+@cindex Flag, example of removing
+@cindex @code{\omit}, example
+@cindex example of @code{\omit}
 
-@lilypond[quote,fragment,relative=2,verbatim]
+@lilypond[quote,verbatim]
 <<
   {
-    \tweak Stem.transparent ##t
-    \tweak Stem.length #8
-    b8~ 8\noBeam
+    \once \omit Stem
+    \once \omit Flag
+    b'8~ 8\noBeam
   }
 \\
-  { b8[ g] }
+  { b'8[ g'] }
 >>
 @end lilypond
 
-@funindex \single
-@cindex tweak, generado a partir de una sobreescritura
-Ahora bien, para la @emph{sobreescritura} de la transparencia de
-un objeto gráfico, podríamos haber usado la abreviatura
-@code{\hide} como se explicó anteriormente.  El trucaje mediante
-@qq{tweak} es una operación diferente que afecta solamente a las
-propiedades generadas a partir de una sola expresión musical.
-Resulta que podemos convertir los overrides o sobreescrituras en
-tweaks o trucajes utilizando @code{\single}, haciendo posible
-volver a escribir el ejemplo anterior como
-
-@lilypond[quote,fragment,relative=2,verbatim]
-<<
-  {
-    \single \hide Stem
-    \single \hide Flag
-    \tweak Stem.length #8
-    b8~ 8\noBeam
-  }
-\\
-  { b8[ g] }
->>
-@end lilypond
+@seealso
+Learning Manual:
+@ref{The once prefix,,The @code{@bs{}once} prefix},
+@ref{The stencil property}.
 
-En este caso particular, la diferencia con @code{\once \hide} no
-es muy apreciable.  Es importante cuando existen varios objetos en
-el mismo punto del tiempo musical (como las notas de un acorde).
-En tal caso, @code{\once} afecta a todos los objetos, mientras que
-@code{\single} solo afecta a uno, aquél que se genera por parte de
-la expresión musical que le sigue inmediatamente.
 
 @node Simulación de un calderón en el MIDI
 @unnumberedsubsubsec Simulación de un calderón en el MIDI
@@ -4190,7 +4235,7 @@ los dos métodos:
     % Visible tempo marking
     \tempo 4=120
     a'4 a a
-    \once \override Score.MetronomeMark.stencil = ##f
+    \once \omit Score.MetronomeMark
     % Invisible tempo marking to lengthen fermata in MIDI
     \tempo 4=80
     a4\fermata |
@@ -4679,10 +4724,10 @@ Vamos a comenzar observando algunos archivos que están en @file{ly/}.
 Abra @file{ly/property-init.ly} con un editor de textos.  El mismo que
 usaría normalmente para los archivos @file{.ly} servirá perfectamente.
 Este archivo contiene las definiciones de todas las instrucciones
-estándar predefinidas de LilyPond, como por ejemplo @code{\stemUp} y
+estándar predefinidas de LilyPond, como por ejemplo @code{\tieUp} y
 @code{\slurDotted}.  Podrá ver que no son nada más que definiciones de
 variables que contienen una o varias instrucciones @code{\override}.
-Por ejemplo, @code{/tieDotted} está definido de tal forma que su valor
+Por ejemplo, @code{\tieDotted} está definido de tal forma que su valor
 es:
 
 @example