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 169ac357c7ba83807695095eecfdae20f482bb75..65d25072558752e8ef3629313859e48ec560ef11 100644 (file)
--- a/Documentation/notation/input.itely
+++ b/Documentation/notation/input.itely
@@ -493,7 +493,7 @@ circumstances to avoid errors:
 @item After every command or variable, i.e. every item that
 begins with a @code{\} sign.
 @item After every item that is to be interpreted as a Scheme
-expression, i.e. every item that begins with a @code{#} sign.
+expression, i.e. every item that begins with a @code{#}@tie{}sign.
 @item To separate all elements of a Scheme expression.
 @item In @code{lyricmode} to separate all the terms in both
 @code{\override} and @code{\set} commands.  In particular, spaces
@@ -1258,7 +1258,7 @@ been brought into the main file, so the file names they specify
 must all be relative to the directory containing the main file,
 not the directory containing the included file.  However,
 this behavior can be changed by passing the option
-@code{-drelative-includes} option at the command line
+@option{-drelative-includes} option at the command line
 (or by adding @code{#(ly:set-option 'relative-includes #t)}
 at the top of the main input file).  With @code{relative-includes}
 set, the path for each @code{\include} command will be taken
@@ -1329,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.
 
@@ -1406,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}.
@@ -1533,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:
@@ -1742,7 +1770,7 @@ More clip regions can be defined by adding more pairs of
 rhythmic-locations to the list.
 
 In order to use this feature, LilyPond must be invoked with
-@code{-dclip-systems}.  The clips are output as EPS files, and are
+@option{-dclip-systems}.  The clips are output as EPS files, and are
 converted to PDF and PNG if these formats are switched on as well.
 
 For more information on output formats, see @rprogram{Invoking lilypond}.
@@ -1975,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