X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fchanging-defaults.itely;h=ace19d19fb5c51bf893c8743b4cf6d51cd42d1d7;hb=26a079ca2393d053315ef8dbef626c897dc9645a;hp=65a4d8e15bd282bf866751e475dfd1d645f1aa13;hpb=f5d0527b79ec9399139076f8558467ec18e8ea13;p=lilypond.git

diff --git a/Documentation/notation/changing-defaults.itely b/Documentation/notation/changing-defaults.itely
index 65a4d8e15b..ace19d19fb 100644
--- a/Documentation/notation/changing-defaults.itely
+++ b/Documentation/notation/changing-defaults.itely
@@ -8,7 +8,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.15.20"
+@c \version "2.16.0"
 
 @node Changing defaults
 @chapter Changing defaults
@@ -564,12 +564,11 @@ words = \lyricmode { These words fol -- low the mel -- o -- dy }
 
 @c TODO Should this be Modifying engravers or Modifying contexts?
 
-Notation contexts (like @code{Score} and @code{Staff}) not only
-store properties,
-they also contain plug-ins called @q{engravers} that create notation
-elements.  For example, the @code{Voice} context contains a
+Notation contexts (like @code{Score} and @code{Staff}) not only store
+properties, they also contain plug-ins called @q{engravers} that create
+notation elements.  For example, the @code{Voice} context contains a
 @code{Note_heads_engraver} and the @code{Staff} context contains a
-@code{Key_signature_engraver}.
+@code{Key_engraver}.
 
 For a full a description of each plug-in, see
 @ifhtml
@@ -673,98 +672,335 @@ time signature.
 
 @knownissues
 
-Usually the order in which the engravers are specified
-does not matter, but in a few special cases the order
-is important, for example where one engraver writes
-a property and another reads it, or where one engraver
-creates a grob and another must process it.  The order in
-which the engravers are specified is the order in which
-they are called to carry out their processing.
+The order in which the engravers are specified is the order in
+which they are called to carry out their processing.  Usually the
+order in which the engravers are specified does not matter, but in
+a few special cases the order is important, for example where one
+engraver writes a property and another reads it, or where one
+engraver creates a grob and another must process it.
+
+The following orderings are important:
+
+@itemize
+@item
+the @code{Bar_engraver} must normally be first,
+
+@item
+the @code{New_fingering_engraver} must come before the
+@code{Script_column_engraver},
+
+@item
+the @code{Timing_translator} must come before the
+@code{Bar_number_engraver}.
+
+@end itemize
+
+@seealso
+Installed Files:
+@file{ly/engraver-init.ly}.
 
-The following orderings are important: the
-@code{Bar_engraver} must normally be first, and
-the @code{New_fingering_engraver} must come before
-the @code{Script_column_engraver}.  There may be others
-with ordering dependencies.
 
 @node Changing context default settings
 @subsection Changing context default settings
 
+@cindex default context properties, changing
+@cindex context properties, changing defaults
+
+Context and grob properties can be changed with @code{\set}
+and @code{\override} commands, as described in
+@ref{Modifying properties}.  These commands create music events,
+making the changes take effect at the point in time the music
+is being processed.
+
+In contrast, this section explains how to change the @emph{default}
+values of context and grob properties at the time the context is
+created.  There are two ways of doing this.  One modifies the default
+values in all contexts of a particular type, the other modifies the
+default values in just one particular instance of a context.
+
+@menu
+* Changing all contexts of the same type::
+* Changing just one specific context::
+* Order of precedence::
+@end menu
+
+@node Changing all contexts of the same type
+@unnumberedsubsubsec Changing all contexts of the same type
+
+@cindex \context in \layout block
+@funindex \context
+@funindex \layout
+
 The context settings which are to be used by default in
-@code{Score}, @code{Staff} and @code{Voice} contexts may be specified
-in a @code{\layout} block, as illustrated in the following example.
+@code{Score}, @code{Staff}, @code{Voice} and other contexts may be
+specified in a @code{\context} block within any @code{\layout} block.
 The @code{\layout} block should be placed within the @code{\score}
-block to which it is to apply, but outside any music.
+block to which it is to apply, after the music.
 
-Note that the @code{\set} command itself and the context must be
-omitted when the context default values are specified in this way:
+@example
+\layout @{
+  \context @{
+    \Voice
+    [context settings for all Voice contexts]
+  @}
+  \context @{
+    \Staff
+    [context settings for all Staff contexts]
+  @}
+@}
+@end example
+
+The following types of settings may be specified:
+
+@itemize
+@item
+An @code{\override} command, but with the context name omitted
 
 @lilypond[quote,verbatim]
 \score {
   \relative c'' {
-    a4^"Really small, thicker stems, no time signature" a a a
-    a a a a
+    a4^"Thicker stems" a a a
+    a4 a a\ff a
   }
   \layout {
     \context {
       \Staff
-      fontSize = #-4
       \override Stem #'thickness = #4.0
-      \remove "Time_signature_engraver"
     }
   }
 }
 @end lilypond
 
-In this example, the @code{\Staff} command specifies that the
-subsequent specifications are to be applied to all staves within
-this score block.
-
-Modifications can be made to the @code{Score} context or all
-@code{Voice} contexts in a similar way.
+@item
+Directly setting a context property
 
-Context changes can be placed in a variable and applied to a
-@code{\context} definition by prepending the modification with
-@code{\with}:
 @lilypond[quote,verbatim]
-blubb = \with {
-  fontSize = #-4
-  \override Stem #'thickness = #4.0
-  \remove "Time_signature_engraver"
+\score {
+  \relative c'' {
+    a4^"Smaller font" a a a
+    a4 a a\ff a
+  }
+  \layout {
+    \context {
+      \Staff
+      fontSize = #-4
+    }
+  }
 }
+@end lilypond
 
-bla = \with {
-  fontSize = #3
-  \override Stem #'thickness = #-2.0
+@item
+A predefined command such as @code{\dynamicUp} or a music
+expression like @code{\accidentalStyle "dodecaphonic"}
+
+@lilypond[quote,verbatim]
+\score {
+  \relative c'' {
+    a4^"Dynamics above" a a a
+    a4 a a\ff a
+  }
+  \layout {
+    \context {
+      \Voice
+      \dynamicUp
+    }
+    \context {
+      \Staff
+      \accidentalStyle "dodecaphonic"
+    }
+  }
 }
+@end lilypond
 
-melody = \relative c'' {
-  a4 a a a |
-  a4 a a a |
+@item
+A user-defined variable containing a @code{\with} block; for details
+of the @code{\with} block see
+@ref{Changing just one specific context}.
+
+@lilypond[quote,verbatim]
+StaffDefaults = \with {
+  fontSize = #-4
 }
 
 \score {
-  <<
-    \new Staff <<
-      \melody
-      s1*0^"Small, thicker stems, no time signature"
-    >>
-    \new Staff \bla <<
-      \melody
-      s1*0^"Different"
-    >>
-  >>
+  \new Staff {
+    \relative c'' {
+      a4^"Smaller font" a a a
+      a4 a a a
+    }
+  }
   \layout {
     \context {
       \Staff
-      \blubb
+      \StaffDefaults
     }
   }
 }
 @end lilypond
 
-@c TODO: add \with in here.
+@end itemize
 
+Property-setting commands can be placed in a @code{\layout} block
+without being enclosed in a @code{\context} block.  Such settings
+are equivalent to including the same property-setting commands at
+the start of every context of the type specified.  If no context
+is specified @emph{every} bottom-level context is affected, see
+@ref{Bottom-level contexts - voices}.  The syntax of a
+property-setting command in a @code{\layout} block is the same as
+the same command written in the music stream.
+
+@lilypond[quote,verbatim]
+\score {
+  \new Staff {
+    \relative c'' {
+      a4^"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
+@unnumberedsubsubsec Changing just one specific context
+
+@cindex \with
+@funindex \with
+
+The context properties of just one specific context instance can be
+changed in a @code{\with} block.  All other context instances of the
+same type retain the default settings built into LilyPond and modified
+by any @code{\layout} block within scope.  The @code{\with} block
+must be placed immediately after the @code{\new} @var{context-type}
+command:
+
+@example
+\new Staff
+\with @{
+  [context settings for this context instance only]
+@} @{
+...
+@}
+@end example
+
+The following types of settings may be specified:
+
+@itemize
+@item
+An @code{\override} command, but with the context name omitted
+
+@lilypond[quote,verbatim]
+\score {
+  \new Staff {
+    \new Voice
+    \with {
+      \override Stem #'thickness = #4.0
+    }
+    {
+      \relative c'' {
+        a4^"Thick stems" a a a
+        a4 a a a
+      }
+    }
+  }
+}
+@end lilypond
+
+@item
+Directly setting a context property
+
+@lilypond[quote,verbatim]
+\score {
+  <<
+    \new Staff {
+      \relative c'' {
+        a4^"Default font" a a a
+        a4 a a a
+      }
+    }
+    \new Staff
+    \with {
+      fontSize = #-4
+    } {
+      \relative c'' {
+        a4^"Smaller font" a a a
+        a4 a a a
+      }
+    }
+  >>
+}
+@end lilypond
+
+@item
+A predefined command such as @code{\dynamicUp}
+
+@lilypond[quote,verbatim]
+\score {
+  <<
+    \new Staff {
+      \new Voice {
+        \relative c'' {
+          a4^"Dynamics below" a a a
+          a4 a a\ff a
+        }
+      }
+    }
+    \new Staff
+    \with { \accidentalStyle "dodecaphonic" }
+    {
+      \new Voice
+      \with { \dynamicUp }
+      {
+        \relative c'' {
+          a4^"Dynamics above" a a a
+          a4 a a\ff a
+        }
+      }
+    }
+  >>
+}
+@end lilypond
+
+@end itemize
+
+@node Order of precedence
+@unnumberedsubsubsec Order of precedence
+
+The value of a property which applies at a particular time is
+determined as follows:
+
+@itemize
+@item
+if an @code{\override} or @code{\set} command in the input stream is
+in effect that value is used,
+
+@item
+otherwise the default value taken from a @code{\with} statement
+on the context initiation statement is used,
+
+@item
+otherwise the default value taken from the most recent appropriate
+@code{\context} block in the @code{\layout} blocks is used,
+
+@item
+otherwise the LilyPond built-in default is used.
+@end itemize
+
+@seealso
+Learning Manual:
+@rlearning{Modifying context properties}.
+
+Notation Reference:
+@ref{Contexts explained},
+@ref{Bottom-level contexts - voices},
+@ref{The set command},
+@ref{The override command},
+@ref{The \layout block}.
 
 
 @node Defining new contexts
@@ -1008,7 +1244,43 @@ Note that a context will be silently created implicitly if a command
 is encountered when there is no suitable context available to
 contain it.  This can give rise to unexpected new staves or scores.
 
+@cindex alignAboveContext
+@cindex alignBelowContext
+@funindex alignAboveContext
+@funindex alignBelowContext
+
+Sometimes a context is required to exist for just a brief period, a
+good example being the staff context for an ossia.  This is usually
+achieved by introducing the context definition at the appropriate
+place in parallel with corresponding section of the main music.
+By default, the temporary context will be placed below all the
+existing contexts.  To reposition it above the context called
+@qq{main}, it should be defined like this:
+
+@example
+@code{\new Staff \with @{ alignAboveContext = #"main" @} }
+@end example
+
+A similar situation arises when positioning a temporary lyrics
+context within a multi-staved layout such as a @code{ChoirStaff},
+for example, when adding a second verse to a repeated section.
+By default the temporary lyrics context will be placed beneath the
+lower staves.  By defining the temporary lyrics context with
+@code{alignBelowContext} it can be positioned correctly beneath
+the (named) lyrics context containing the first verse.
+
+Examples showing this repositioning of temporary contexts can be
+found elsewhere --- see @rlearning{Nesting music expressions},
+@ref{Modifying single staves} and @ref{Techniques specific to lyrics}.
+
 @seealso
+Learning Manual:
+@rlearning{Nesting music expressions}.
+
+Notation Reference:
+@ref{Modifying single staves},
+@ref{Techniques specific to lyrics}.
+
 Application Usage:
 @rprogram{An extra staff appears}.
 
@@ -1802,11 +2074,12 @@ accomplished with the @code{\tweak} command, which has the following
 syntax:
 
 @example
-\tweak #'@code{grob-property} #@code{value}
+\tweak @var{layout-object} #'@var{grob-property} @var{value}
 @end example
 
-The @code{\tweak} command applies to the object that immediately
-follows @code{value} in the music stream.
+Specifying @var{layout-object} is optional.
+The @code{\tweak} command applies to the music object that immediately
+follows @var{value} in the music stream.
 
 @ignore
 In some cases, it is possible to take a short-cut for tuning
@@ -1906,23 +2179,33 @@ c-\tweak #'thickness #5 ( d e f)
 For the @code{\tweak} command to work, it must
 remain immediately adjacent to the object to which it is
 to apply after the input file has been converted to a music stream.
-At times, LilyPond may insert additional items into the music stream
-during the parsing process.  For example, when a note that is not
-explicitly part of a chord will be placed in a chord by LilyPond,
-so notes to be modified with @code{\tweak} must be placed inside
-a chord construct:
+Tweaking a whole chord does not do anything since its music event
+only acts as a container, and all layout objects are created from events
+inside of the @code{EventChord}:
 
 @lilypond[relative=2,verbatim,quote]
 \tweak #'color #red c4
-<\tweak #'color #red c>4
+\tweak #'color #red <c e>4
+<\tweak #'color #red c e>4
+@end lilypond
+
+The simple @code{\tweak} command cannot be used to modify any object
+that is not directly created from the input.  In particular
+it will not affect stems, automatic
+beams or accidentals, since these are generated later by
+@code{NoteHead} layout objects rather than by music elements in the
+input stream.
+
+Such indirectly created layout objects can be tweaked using the explicit
+form of the @code{\tweak} command:
+
+@lilypond[relative=2,verbatim,quote]
+\tweak Stem #'color #red
+\tweak Beam #'color #green c8 e
+<c e \tweak Accidental #'font-size #-3 ges>4
 @end lilypond
 
-The @code{\tweak} command cannot be used to modify any item
-that does not appear explicitly in the input file.  In particular
-it cannot be used to modify stems,
-beams or accidentals directly, since these are generated later by
-note heads, rather than by music elements in the input stream.
-Nor can @code{\tweak} be used to modify clefs or time
+@code{\tweak} cannot be used to modify clefs or time
 signatures, since these become separated from any preceding
 @code{\tweak} command in the input stream by the automatic
 insertion of extra elements required to specify the context.
@@ -1955,19 +2238,13 @@ Extending LilyPond:
 @rextend{Displaying music expressions}.
 
 @knownissues
-@cindex tweaks in a variable
-
-The @code{\tweak} command cannot be used inside a variable.
-
-@cindex tweaks in lyrics
-The @code{\tweak} commands cannot be used in @code{\lyricmode}.
 
 @cindex tweaking control points
 @cindex control points, tweaking
 
-The @code{\tweak} command will apply to only the first of several
-generated ties in a chord.
-
+The @code{\tweak} command cannot be used to modify the control
+points of just one of several ties in a chord, other than the first
+one encountered in the input file.
 
 @node set versus override
 @subsection @code{\set} vs. @code{\override}
@@ -2264,31 +2541,30 @@ c2^( c)
 
 @strong{The direction property}
 
-The position or direction of many layout objects is controlled
-by the @code{direction} property.
+The position or direction of many layout objects is controlled by the
+@code{direction} property.
 
-The value of the @code{direction} property may be
-set to @code{1}, meaning @qq{up} or @qq{above}, or to @w{@code{-1}},
-meaning @qq{down} or @qq{below}.  The symbols @code{UP} and
-@code{DOWN} may be used instead of @code{1} and @w{@code{-1}}
-respectively.  The default direction may be specified by setting
-@code{direction} to @code{0} or @code{CENTER}.  Alternatively,
-in many cases predefined commands
-exist to specify the direction.  These are all of the form
+The value of the @code{direction} property may be set to @code{1},
+meaning @qq{up} or @qq{above}, or to @w{@code{-1}}, meaning @qq{down} or
+@qq{below}.  The symbols @code{UP} and @code{DOWN} may be used instead
+of @code{1} and @w{@code{-1}} respectively.  The default direction may
+be specified by setting @code{direction} to @code{0} or @code{CENTER}.
+Alternatively, in many cases predefined commands exist to specify the
+direction.  These are of the form
 
-@noindent
-@code{\xxxUp}, @code{xxxDown}, @code{xxxNeutral}
+@example
+@code{\xxxUp}, @code{\xxxDown} or @code{\xxxNeutral}
+@end example
 
 @noindent
-where @code{xxxNeutral} means @qq{use the default direction}.
+where @code{\xxxNeutral} means @qq{use the default} direction.
 See @rlearning{Within-staff objects}.
 
-In a few cases, arpeggio being the only common example, the value
-of the @code{direction} property specifies whether the object
-is to be placed to the right or left of the parent object.  In
-this case @w{@code{-1}} or @code{LEFT} means @qq{to the left} and
-@code{1} or @code{RIGHT} means @qq{to the right}.  @code{0}
-or @code{CENTER} means @qq{use the default} direction, as before.
+In a few cases, arpeggio for example, the value of the @code{direction}
+property can specify whether the object is to be placed to the right or
+left of the parent.  In this case @w{@code{-1}} or @code{LEFT} means
+@qq{to the left} and @code{1} or @code{RIGHT} means @qq{to the right}.
+@code{0} or @code{CENTER} means @qq{use the default} direction.
 
 @ignore
 These all have side-axis set to #X
@@ -2310,6 +2586,17 @@ c2( c)
 c2( c)
 @end lilypond
 
+In polyphonic music, it is generally better to specify an explicit
+@code{voice} than change an object's direction.  For more information.
+See @ref{Multiple voices}.
+
+@seealso
+Learning Manual:
+@rlearning{Within-staff objects}.
+
+Notation Reference:
+@ref{Multiple voices}.
+
 
 @node Distances and measurements
 @subsection Distances and measurements
@@ -2850,7 +3137,7 @@ by pre-defined functions, defined in @file{scm/output-lib.scm},
 where the last three columns indicate whether the layout objects
 will be visible in the positions shown at the head of the columns:
 
-@multitable {@code{begin-of-line-invisible}} {@code{'#(#t #t #t)}} {yes} {yes} {yes}
+@multitable {@code{begin-of-line-invisible}} {@code{'#(#t #t #t)}} {Before} {At no} {After}
 @headitem Function                   @tab Vector                  @tab Before @tab At no    @tab After
 @headitem form                       @tab form                    @tab break  @tab break    @tab break
 
@@ -3831,7 +4118,8 @@ must return @code{#t}.
 @item @code{@var{@dots{}music@dots{}}}
 @tab normal LilyPond input, using @code{$} (in places where only
 Lilypond constructs are allowed) or @code{#} (to use it as a Scheme
-value or music function argument) to reference arguments
+value or music function argument or music inside of music lists) to
+reference arguments
 (eg. @samp{#arg1}).
 @end multitable
 
@@ -3905,20 +4193,17 @@ padText =
 In addition to numbers, we can use music expressions such
 as notes for arguments to music functions:
 
-@c TODO: use a better example (the music argument is redundant).
-
 @lilypond[quote,verbatim,ragged-right]
 custosNote =
 #(define-music-function
      (parser location note)
      (ly:music?)
    #{
-     \once \override Voice.NoteHead #'stencil =
-       #ly:text-interface::print
-     \once \override Voice.NoteHead #'text =
-       \markup \musicglyph #"custodes.mensural.u0"
-     \once \override Voice.Stem #'stencil = ##f
-     $note
+     \tweak NoteHead #'stencil #ly:text-interface::print
+     \tweak NoteHead #'text
+        \markup \musicglyph #"custodes.mensural.u0"
+     \tweak Stem #'stencil ##f
+     #note
    #})
 
 \relative c' { c4 d e f \custosNote g }
@@ -3930,7 +4215,7 @@ Substitution functions with multiple arguments can be defined:
 tempoPadded =
 #(define-music-function
      (parser location padding tempotext)
-     (number? string?)
+     (number? markup?)
    #{
      \once \override Score.MetronomeMark #'padding = #padding
      \tempo \markup { \bold #tempotext }
@@ -3939,7 +4224,7 @@ tempoPadded =
 \relative c'' {
   \tempo \markup { "Low tempo" }
   c4 d e f g1
-  \tempoPadded #4.0 #"High tempo"
+  \tempoPadded #4.0 "High tempo"
   g4 f e d c1
 }
 @end lilypond