X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Finput.itely;h=8cede953f0e85e8469036452fe4651f44d721b5f;hb=7b4cd7b6b3bc0f905e4143120440b40c940c1fdc;hp=315660b68d664dfe6371d3604ed9696754322b21;hpb=70cc6f11795ab109dbe39c608be9bbe6ea95ced0;p=lilypond.git diff --git a/Documentation/notation/input.itely b/Documentation/notation/input.itely index 315660b68d..8cede953f0 100644 --- a/Documentation/notation/input.itely +++ b/Documentation/notation/input.itely @@ -8,7 +8,7 @@ Guide, node Updating translation committishes.. @end ignore -@c \version "2.17.6" +@c \version "2.19.2" @node General input and output @chapter General input and output @@ -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 the third quarter-note 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. -More clip regions can be defined by adding more pairs of -rhythmic-locations to the list. +@seealso +Notation Reference: +@ref{The layout block}. + +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 @@ -2772,6 +2819,9 @@ crescendi and decrescendi cannot affect the volume of a single note. Some MIDI players may not always correctly handle tempo changes in the midi output. +Changes to @code{midiInstrument} (and other MIDI options) at the +beginning of a staff may appear twice in the MIDI output. + @node MIDI Instruments @subsection MIDI Instruments @@ -3057,8 +3107,8 @@ volume is limited to the range 0.2 - 0.5. \set Staff.midiInstrument = #"flute" \new Voice \relative c''' { r2 g\mp g fis~ - fis4 g8 fis e2~ - e4 d8 cis d2 + 4 g8 fis e2~ + 4 d8 cis d2 } } \new Staff { @@ -3114,8 +3164,8 @@ volume of the flute. \set Staff.midiMaximumVolume = #0.9 \new Voice \relative c''' { r2 g\mp g fis~ - fis4 g8 fis e2~ - e4 d8 cis d2 + 4 g8 fis e2~ + 4 d8 cis d2 } } \new Staff { @@ -3188,8 +3238,8 @@ the same values as the previous example. \set Staff.midiInstrument = #"flute" \new Voice \relative c''' { r2 g\mp g fis~ - fis4 g8 fis e2~ - e4 d8 cis d2 + 4 g8 fis e2~ + 4 d8 cis d2 } } \new Staff {