@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}.
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
@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
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
@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:
}
\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
* 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
projects / lilypond.git / blobdiff