X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Finput.itely;h=896caf2de2f0066035ce87a480db26c0d60549b3;hb=0b58c7d1f556ce0a62c3bcdce172e0f4fe9d19f0;hp=fc2ead626d388a27ad52491105450a6ac0c5dfd9;hpb=59703bdfd8e6f35f7ac6c0f8ce47f7f7643facd3;p=lilypond.git diff --git a/Documentation/notation/input.itely b/Documentation/notation/input.itely index fc2ead626d..896caf2de2 100644 --- a/Documentation/notation/input.itely +++ b/Documentation/notation/input.itely @@ -2071,12 +2071,9 @@ 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}. @@ -2091,7 +2088,7 @@ to tagged music is as follows: Tagged music preceded by @code{\keepWithTag #'@var{name}} or @code{\keepWithTag #'(@var{name1} @var{name2}@dots{})} @tab Untagged music and music tagged with any of the given tag - names is included; + names is included; music tagged with any other tag name is excluded. @item Tagged music preceded by @code{\removeWithTag #'@var{name}} or @@ -2106,9 +2103,15 @@ Tagged music not preceded by either @code{\keepWithTag} or @end multitable The arguments of the @code{\tag}, @code{\keepWithTag} and -@code{\removeWithTag} commands should be a symbol -(such as @code{#'score} or @code{#'part}), followed -by a music expression. +@code{\removeWithTag} commands should be a symbol or list of +symbols (such as @code{#'score} or @code{#'(violinI violinII}), +followed by a music expression. If @emph{and only if} the symbols +are valid LilyPond identifiers (alphabetic characters only, no +numbers, underscores, or dashes) which cannot be confused with notes, +the @code{#'} may be omitted and, as a shorthand, a list of symbols +can use the dot separator: i.e. @code{\tag #'(violinI violinII)} can +be written @code{\tag violinI.violinII}. The same applies to +@code{\keepWithTag} and @code{\removeWithTag}. In the following example, we see two versions of a piece of music, one showing trills with the usual notation, and one with trills @@ -2212,6 +2215,38 @@ Usually you would rather want to use a single @code{\keepWithTag} command with a list of multiple tags: this will only remove tagged sections not given in @emph{any} of the tags. +@cindex tag groups +@funindex \tagGroup +While @code{\keepWithTag} is convenient when dealing with +@emph{one} set of alternatives, the removal of music tagged with +@emph{unrelated} tags is problematic when using tags for more than +one purpose. For that reason, @q{tag groups} of related tags can +be declared: + +@example +\tagGroup #'(violinI violinII viola cello) +@end example + +declares the respective tags as belonging to one tag group. + +@example +\keepWithTag #'violinI @dots{} +@end example + +will then only be concerned with tags from @code{violinI}'s tag +group: any element of the included music that is tagged with one +or more of tags from this set but @emph{not} with @code{violinI} +will get removed. + +To any @code{\keepWithTag} command, only tags from the tag groups +of the tags given in the command are visible. + +Tags cannot be members of more than one tag group. + +@funindex \pushToTag +@funindex \appendToTag +@cindex splice into tagged music + 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 @@ -2233,9 +2268,7 @@ test = { \tag #'here { \tag #'here <> } } @end lilypond Both commands get a tag, the material to splice in at every occurence of -the tag, and the tagged expression. The commands make sure to -copy everything that they change so that the original @code{\test} -retains its meaning. +the tag, and the tagged expression. @seealso Learning Manual: @@ -2405,7 +2438,7 @@ lyrics and as stand-alone text below the score: } \addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } } } -\markup { "Copyright 2008--2014" \char ##x00A9 } +\markup { "Copyright 2008--2015" \char ##x00A9 } @end lilypond @cindex copyright sign @@ -2481,40 +2514,54 @@ Installed Files: * Replacing the notation font:: @end menu +@funindex clip-regions +@cindex Fragments, music +@cindex Music fragments + @node Extracting fragments of music @subsection Extracting fragments of music -It is possible to quote small fragments of a large score directly from -the output. This can be compared to clipping a piece of a paper score -with scissors. - -This is done by defining the measures that need to be cut out -separately. For example, including the following definition +It is possible to output one or more fragments of a score by defining +the explicit location of the music to be extracted within the +@code{\layout} block of the the input file using the @code{clip-regions} +function, and then running LilyPond with the @option{-dclip-systems} +option; - -@verbatim -\layout { +@example +\layout @{ clip-regions = #(list (cons (make-rhythmic-location 5 1 2) (make-rhythmic-location 7 3 4))) -} -@end verbatim +@} +@end example @noindent -will extract a fragment starting halfway the fifth measure, ending in -the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note -in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7. +This example will extract a single fragment of the input file +@emph{starting} after a half-note duration in fifth measure +(@code{5 1 2}) and @emph{ending} after three, quarter notes in the +seventh measure (@code{7 3 4}). + +Additional fragments can be extracted by adding more pairs of +@code{make-rhythmic-location} entries to the @code{clip-regions} list in +the @code{\layout} block. + +By default, each music fragment will be output as a separate @code{EPS} +file, but other formats such as @code{PDF} or @code{PNG} can also be +created if required. The extracted music is output as if had been +literally @q{cut} from the original printed score so if a fragment runs +over one or more lines, a separate ouput file for each line will be +generated. + +@seealso +Notation Reference: +@ref{The layout block}. -More clip regions can be defined by adding more pairs of -rhythmic-locations to the list. +Application Usage +@rprogram{Command-line usage}. -In order to use this feature, LilyPond must be invoked with -@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}. @node Skipping corrected music @subsection Skipping corrected music