Add \pushAtTag \appendAtTag music functions and map-music-copy function

[lilypond.git] / Documentation / notation / input.itely

diff --git a/Documentation/notation/input.itely b/Documentation/notation/input.itely
index 59b9c1d9cf112d0226365f8e7578c175cb8cbce4..65d25072558752e8ef3629313859e48ec560ef11 100644 (file)
--- a/Documentation/notation/input.itely
+++ b/Documentation/notation/input.itely
@@ -546,32 +546,6 @@ both types are entered using a @code{\header} block.
 If the book only has a single score, the @code{\header} block may be
 placed inside or outside of the @code{\score} block.
 
-The default behavior, when the @code{\header} has been defined inside
-the @code{\score} block, is to print only the @code{piece} and
-@code{opus} fields:
-
-@lilypond[papersize=a5,quote,verbatim,noragged-right]
-\score {
-  { c'4 }
-  \header {
-    title = "title"  % not printed
-    piece = "piece"
-    opus = "opus"
-  }
-}
-@end lilypond
-
-@funindex print-all-headers
-@noindent
-You may change this behavior (and print all the headers when defining
-@code{\header} inside @code{\score}) by using
-
-@example
-\paper@{
-  print-all-headers = ##t
-@}
-@end example
-
 @warning{Remember when adding a @bs{}@code{header} block inside a
 @bs{}@code{score} block, that the music expression must come before the
 @bs{}@code{header} block.}
@@ -825,7 +799,7 @@ footer and title text within the @code{\header} block.
   { s1 }
   \header {
     piece = \markup { \fontsize #4 \bold "PRAELUDIUM I" }
-    opus = \markup { \italic "(Excerpt)" }
+    subtitle = \markup { \italic "(Excerpt)" }
   }
 }
 @end lilypond
@@ -1355,7 +1329,10 @@ of different versions of a score from the same music source.
 Variables are perhaps most useful for combining lengthy sections
 of music and/or annotation in various ways, while tags are more
 useful for selecting one from several alternative shorter sections
-of music.  Whichever method is used, separating the notation from
+of music.  You can also employ tags for splicing pieced of music
+together at several places.
+
+Whichever method is used, separating the notation from
 the structure of the score will make it easier to change the
 structure while leaving the notation untouched.
 
@@ -1432,9 +1409,12 @@ LilyPond files}.
 @funindex \tag
 @funindex \keepWithTag
 @funindex \removeWithTag
+@funindex \pushToTag
+@funindex \appendToTag
 @cindex tag
 @cindex keep tagged music
 @cindex remove tagged music
+@cindex splice into tagged music
 
 The @code{\tag #'@var{partA}} command marks a music expression
 with the name @var{partA}.
@@ -1559,6 +1539,28 @@ expression will cause @emph{all} tagged sections to be removed, as
 the first filter will remove all tagged sections except the one
 named, and the second filter will remove even that tagged section.
 
+Sometimes you want to splice some music at a particular place in an
+existing music expression.  You can use @code{\pushToTag} and
+@code{\appendToTag} for adding material at the front or end of the
+@code{elements} of an existing music construct.  Not every music
+construct has @code{elements}, but sequential and simultaneous music are
+safe bets:
+
+@lilypond[verbatim,quote]
+test = { \tag #'here { \tag #'here <<c''>> } }
+
+{
+  \pushToTag #'here \pushToTag #'here
+     \pushToTag #'here \test g' e' c'
+  \appendToTag #'here \appendToTag #'here
+     \appendToTag #'here \test g' e' c'
+}
+@end lilypond
+
+Both commands get a tag, the tagged expression, and finally the material
+you want to splice in at every given tag.  The commands make sure to
+copy everything that they change so that the original @code{\test}
+retains its meaning.
 
 @seealso
 Learning Manual:
@@ -2001,7 +2003,7 @@ instrument is used.
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {changing-midi-output-to-one-channel-per-voice.ly}
 
 @knownissues