From: Trevor Daniels <t.daniels@treda.co.uk>
Date: Sat, 29 Dec 2012 12:34:30 +0000 (+0000)
Subject: Doc: Clarify Context creation (3006)
X-Git-Tag: release/2.17.10-1~33
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=d409c67cbbdebe840220c17f796544a8a9dd193e;p=lilypond.git

Doc: Clarify Context creation (3006)

  - change heading and rewrite section to be more precise
    and accurate
  - move \applyOutput to Extending
---

diff --git a/Documentation/extending/programming-interface.itely b/Documentation/extending/programming-interface.itely
index 0c1601f50f..9fd578b2bd 100644
--- a/Documentation/extending/programming-interface.itely
+++ b/Documentation/extending/programming-interface.itely
@@ -1028,19 +1028,18 @@ current bar number on the standard output during the compile:
 @cindex calling code on layout objects
 @funindex \applyOutput
 
-
 The most versatile way of tuning an object is @code{\applyOutput} which
 works by inserting an event into the specified context
 (@rinternals{ApplyOutputEvent}).  Its syntax is
 @example
-\applyOutput @var{context} @var{proc}
+\applyOutput @var{Context} @var{proc}
 @end example
 
 @noindent
 where @code{@var{proc}} is a Scheme function, taking three arguments.
 
 When interpreted, the function @code{@var{proc}} is called for
-every layout object found in the context @code{@var{context}} at
+every layout object found in the context @code{@var{Context}} at
 the current time step, with the following arguments:
 @itemize
 @item the layout object itself,
@@ -1069,6 +1068,14 @@ note-heads on the center-line and next to it:
 }
 @end lilypond
 
+To have @var{function} interpreted at the @code{Score} or @code{Staff}
+level use these forms
+
+@example
+\applyOutput #'Score #@var{function}
+\applyOutput #'Staff #@var{function}
+@end example
+
 
 @node Callback functions
 @section Callback functions
diff --git a/Documentation/extending/scheme-tutorial.itely b/Documentation/extending/scheme-tutorial.itely
index a87c6f91f0..b73c2bb9fd 100644
--- a/Documentation/extending/scheme-tutorial.itely
+++ b/Documentation/extending/scheme-tutorial.itely
@@ -1341,7 +1341,7 @@ doubleSlur = #(define-music-function (parser location note) (ly:music?)
 @subsection Adding articulation to notes (example)
 
 The easy way to add articulation to notes is to merge two music
-expressions into one context, as explained in @ruser{Creating contexts}.
+expressions into one context.
 However, suppose that we want to write a music function that does this.
 This will have the additional advantage that we can use that music
 function to add an articulation (like a fingering instruction) to a
diff --git a/Documentation/learning/fundamental.itely b/Documentation/learning/fundamental.itely
index 434890eb0b..e1645dae7a 100644
--- a/Documentation/learning/fundamental.itely
+++ b/Documentation/learning/fundamental.itely
@@ -1546,7 +1546,7 @@ use in the section on lyrics, see @ref{Voices and vocals}.
 
 
 @seealso
-Notation Reference: @ruser{Creating contexts}.
+Notation Reference: @ruser{Creating and referencing contexts}.
 
 
 @node Engravers explained
diff --git a/Documentation/notation/changing-defaults.itely b/Documentation/notation/changing-defaults.itely
index bc7a7b7b52..e0439f321a 100644
--- a/Documentation/notation/changing-defaults.itely
+++ b/Documentation/notation/changing-defaults.itely
@@ -59,7 +59,7 @@ This section describes what contexts are, and how to modify them.
 
 @menu
 * Contexts explained::
-* Creating contexts::
+* Creating and referencing contexts::
 * Keeping contexts alive::
 * Modifying context plug-ins::
 * Changing context default settings::
@@ -268,145 +268,216 @@ context.
 
 @end ignore
 
-@node Creating contexts
-@subsection Creating contexts
-
-@c TODO more complete descriptions rather than learning style
-
-For scores with only one voice and one staff, contexts are
-created automatically.  For more complex scores, it is necessary to
-create them by hand.  There are three commands that do this.
-
-@itemize
-
-@item
-The easiest command is @code{\new}, and it also the quickest to type.
-It is prepended to a music expression, for example
+@node Creating and referencing contexts
+@subsection Creating and referencing contexts
 
 @funindex \new
+@funindex \context
 @cindex new contexts
-@cindex Context, creating
+@cindex referencing contexts
+@cindex Contexts, creating and referencing
+
+LilyPond will create lower-level contexts automatically if a music
+expression is encountered before a suitable context exists, but this
+is usually successful only for simple scores or music fragments like
+the ones in the documentation.  For more complex scores it is
+advisable to specify all contexts explicitly with either the
+@code{\new} or @code{\context} command.  The syntax of
+these two commands is very similar:
 
 @example
-\new @var{type} @var{music expression}
+[\new | \context] @var{Context} [ = @var{name}] [@var{music-expression}]
 @end example
 
 @noindent
-where @var{type} is a context name (like @code{Staff} or
-@code{Voice}).  This command creates a new context, and starts
-interpreting the @var{music expression} with that.
+where either @code{\new} or @code{\context} may be specified.
+@var{Context} is the type of context which is to be created,
+@var{name} is an optional name to be given to the particular context
+being created and @var{music-expression} is a single music expression
+that is to be interpreted by the engravers and performers in this
+context.
 
-A practical application of @code{\new} is a score with many
-staves.  Each part that should be on its own staff, is preceded with
-@code{\new Staff}.
+The @code{\new} prefix without a name is commonly used to create
+scores with many staves:
 
-@lilypond[quote,verbatim,relative=2,ragged-right]
+@lilypond[quote,verbatim,relative=2]
 <<
-  \new Staff { c4 c }
-  \new Staff { d4 d }
+  \new Staff {
+    % leave the Voice context to be created implicitly
+    c4 c
+  }
+  \new Staff {
+    d4 d
+  }
 >>
 @end lilypond
 
-The @code{\new} command may also give a name to the context,
+@noindent
+and to place several voices into one staff:
 
-@example
-\new @var{type} = @var{id} @var{music}
-@end example
-However, this user specified name is only used if there is no other
-context already earlier with the same name.
+@lilypond[quote,verbatim,relative=2]
+<<
+  \new Staff <<
+    \new Voice {
+      \voiceOne
+      c8 c c4 c c
+    }
+    \new Voice {
+      \voiceTwo
+      g4 g g g
+    }
+  >>
+>>
+@end lilypond
 
+@noindent
+@code{\new} should always be used to specify unnamed contexts.
 
-@funindex \context
+The difference between @code{\new} and @code{\context} is in the
+action taken:
 
+@itemize
 @item
-Like @code{\new}, the @code{\context} command also directs a music
-expression to a context object, but gives the context an explicit name.  The
-syntax is
+@code{\new} with or without a name will always create a fresh,
+distinct, context, even if one with the same name already exists:
 
-@example
-\context @var{type} = @var{id} @var{music}
-@end example
+@lilypond[quote,verbatim,relative=2]
+<<
+  \new Staff <<
+    \new Voice = "A" {
+      \voiceOne
+      c8 c c4 c c
+    }
+    \new Voice = "A" {
+      \voiceTwo
+      g4 g g g
+    }
+  >>
+>>
+@end lilypond
 
-This form will search for an existing context of type @var{type}
-called @var{id}.  If that context does not exist yet, a new
-context with the specified name is created.  This is useful if
-the context is referred to later on.  For example, when
-setting lyrics the melody is in a named context
+@item
+@code{\context} with a name specified will create a distinct context
+only if a context of the same type with the same name in the same
+context hierarchy does not already exist.  Otherwise it will be taken
+as a reference to that previously created context, and its music
+expression will be passed to that context for interpretation.
 
-@example
-\context Voice = "@b{tenor}" @var{music}
-@end example
+One application of named contexts is in separating the score layout
+from the musical content.  Either of these two forms is valid:
 
-@noindent
-so the texts can be properly aligned to its notes,
+@lilypond[quote,verbatim]
+\score {
+  <<
+    % score layout
+    \new Staff <<
+      \new Voice = "one" {
+        \voiceOne
+      }
+      \new Voice = "two" {
+        \voiceTwo
+      }
+    >>
 
-@example
-\new Lyrics \lyricsto "@b{tenor}" @var{lyrics}
-@end example
+    % musical content
+    \context Voice = "one" {
+      \relative c'' {
+        c4 c c c
+      }
+    }
+    \context Voice = "two" {
+      \relative c'' {
+        g8 g g4 g g
+      }
+    }
+  >>
+}
+@end lilypond
 
-@noindent
+@lilypond[quote,verbatim]
+\score {
+  <<
+    % score layout
+    \new Staff <<
+      \context Voice = "one" {
+        \voiceOne
+      }
+      \context Voice = "two" {
+        \voiceTwo
+      }
+    >>
+
+    % musical content
+    \context Voice = "one" {
+      \relative c'' {
+        c4 c c c
+      }
+    }
+    \context Voice = "two" {
+      \relative c'' {
+        g8 g g4 g g
+      }
+    }
+  >>
+}
+@end lilypond
 
-Another possible use of named contexts is funneling two different
-music expressions into one context.  In the following example,
-articulations and notes are entered separately,
+@noindent
+Alternatively, variables may be employed to similar effect.  See
+@rlearning{Organizing pieces with variables}.
 
-@example
-music = @{ c4 c4 @}
-arts = @{ s4-. s4-> @}
-@end example
+@item
 
-They are combined by sending both to the same @code{Voice} context,
+@code{\context} with no name will match the first of any previously
+created contexts of the same type in the same context heirarchy,
+even one that has been given a name, and its music expression will be
+passed to that context for interpretation.  This form is rarely
+useful.  However, @code{\context} with no name and no music expression
+is used to set the context in which a Scheme procedure specified with
+@code{\applyContext} is executed:
 
 @example
-<<
-  \new Staff \context Voice = "A" \music
-  \context Voice = "A" \arts
->>
+\new Staff \relative c' @{
+  c1
+  \context Timing
+  \applyContext #(lambda (ctx)
+                   (newline)
+                   (display (ly:context-current-moment ctx)))
+  c1
+@}
 @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
 
-With this mechanism, it is possible to define an Urtext (original
-edition), with the option to put several distinct articulations on the
-same notes.
+@end itemize
 
-@cindex creating contexts
+A context must be named if it is to be referenced later, for example
+when lyrics are associated with music:
 
-@item
-The third command for creating contexts is
 @example
-\context @var{type} @var{music}
+\new Voice = "tenor" @var{music}
+...
+\new Lyrics \lyricsto "tenor" @var{lyrics}
 @end example
 
-
 @noindent
-This is similar to @code{\context} with @code{= @var{id}}, but matches
-any context of type @var{type}, regardless of its given name.
+For details of associating lyrics with music see
+@ref{Automatic syllable durations}.
 
-This variant is used with music expressions that can be interpreted at
-several levels.  For example, the @code{\applyOutput} command (see
-@rextend{Running a function on all layout objects}).  Without an explicit
-@code{\context}, it is usually applied to @code{Voice}
+The properties of all contexts of a particular type can be modified
+in a @code{\layout} block (with a different syntax), see
+@ref{Changing all contexts of the same type}.  This construct also
+provides a means of keeping layout instructions separate from the
+musical content.  If a single context is to be modified, a @code{\with}
+block must be used, see @ref{Changing just one specific context}.
 
-@example
-\applyOutput #'@var{context} #@var{function}   % apply to Voice
-@end example
+@seealso
 
-To have it interpreted at the @code{Score} or @code{Staff} level use
-these forms
+Learning Manual:
+@rlearning{Organizing pieces with variables}.
 
-@example
-\applyOutput #'Score #@var{function}
-\applyOutput #'Staff #@var{function}
-@end example
+Notation Reference:
+@ref{Changing just one specific context},
+@ref{Automatic syllable durations}.
 
-@end itemize
 
 @node Keeping contexts alive
 @subsection Keeping contexts alive
diff --git a/Documentation/notation/staff.itely b/Documentation/notation/staff.itely
index b1558e72df..6c7753e719 100644
--- a/Documentation/notation/staff.itely
+++ b/Documentation/notation/staff.itely
@@ -69,7 +69,7 @@ grouping staves.
 
 @notation{Staves} (singular: @notation{staff}) are created with
 the @code{\new} or @code{\context} commands.  For details, see
-@ref{Creating contexts}.
+@ref{Creating and referencing contexts}.
 
 The basic staff context is @code{Staff}:
 
@@ -124,7 +124,7 @@ Music Glossary:
 @rglos{staves}.
 
 Notation Reference:
-@ref{Creating contexts},
+@ref{Creating and referencing contexts},
 @ref{Percussion staves},
 @ref{Showing melody rhythms},
 @ref{Default tablatures},
diff --git a/Documentation/notation/vocal.itely b/Documentation/notation/vocal.itely
index 70c502da0e..89e08f4409 100644
--- a/Documentation/notation/vocal.itely
+++ b/Documentation/notation/vocal.itely
@@ -1080,7 +1080,7 @@ Learning Manual:
 
 Notation Reference:
 @ref{Context layout order},
-@ref{Creating contexts}.
+@ref{Creating and referencing contexts}.
 
 
 @node Placing syllables horizontally