From f408a195b952e485245c2e37e336fd010a240dfa Mon Sep 17 00:00:00 2001 From: Graham Percival Date: Tue, 1 Mar 2005 07:18:22 +0000 Subject: [PATCH] Moved a bunch of stuff to/from Basic. --- Documentation/user/advanced-notation.itely | 519 ++++++++++++++++----- 1 file changed, 411 insertions(+), 108 deletions(-) diff --git a/Documentation/user/advanced-notation.itely b/Documentation/user/advanced-notation.itely index e86e1c59f0..e1e1019375 100644 --- a/Documentation/user/advanced-notation.itely +++ b/Documentation/user/advanced-notation.itely @@ -16,6 +16,7 @@ This chapter deals with rarely-used and advanced notation. * Orchestral music:: * Contemporary notation:: * Educational use:: +* Other stuff:: @end menu @@ -181,7 +182,6 @@ notes and rhythms. * Text scripts:: * Text spanners:: * Analysis brackets:: -* Articulations:: @end menu @@ -326,113 +326,6 @@ Program reference: @internalsref{HorizontalBracket}, Examples: @inputfileref{input/@/regression,note@/-group@/-bracket@/.ly}. -@node Articulations -@subsection Articulations -@cindex Articulations - -@cindex articulations -@cindex scripts -@cindex ornaments - -A variety of symbols can appear above and below notes to indicate -different characteristics of the performance. They are added to a note -by adding a dash and the character signifying the -articulation. They are demonstrated here - -@lilypondfile[quote,raggedright]{script-abbreviations.ly} - -The meanings of these shorthands can be changed. See -@file{ly/@/script@/-init@/.ly} for examples. - - -The script is automatically placed, but the direction can be forced as -well. Like other pieces of LilyPond code, @code{_} will place them -below the staff, and @code{^} will place them above. - - -@lilypond[quote,raggedright,fragment,verbatim] -c''4^^ c''4_^ -@end lilypond - -Other symbols can be added using the syntax -@var{note}@code{\}@var{name}. Again, they -can be forced up or down using @code{^} and @code{_}, -e.g., - -@lilypond[quote,raggedright,verbatim,fragment,relative=2] -c\fermata c^\fermata c_\fermata -@end lilypond - - - -@cindex accent -@cindex marcato -@cindex staccatissimo -@cindex espressivo -@cindex fermata -@cindex stopped -@cindex staccato -@cindex portato -@cindex tenuto -@cindex upbow -@cindex downbow -@cindex foot marks -@cindex organ pedal marks -@cindex turn -@cindex open -@cindex flageolet -@cindex reverseturn -@cindex trill -@cindex prall -@cindex mordent -@cindex prallprall -@cindex prallmordent -@cindex prall, up -@cindex prall, down -@cindex mordent -@cindex thumb marking -@cindex segno -@cindex coda -@cindex varcoda - -Here is a chart showing all scripts available, - -@lilypondfile[raggedright,quote]{script-chart.ly} - - -The vertical ordering of scripts is controlled with the -@code{script-priority} property. The lower this number, the closer it -will be put to the note. In this example, the -@internalsref{TextScript} (the sharp symbol) first has the lowest -priority, so it is put lowest in the first example. In the second, the -prall trill (the @internalsref{Script}) has the lowest, so it is on the -inside. When two objects have the same priority, the order in which -they are entered decides which one comes first. - - -@lilypond[verbatim,relative=3,raggedright,fragment,quote] -\once \override TextScript #'script-priority = #-100 -a4^\prall^\markup { \sharp } - -\once \override Script #'script-priority = #-100 -a4^\prall^\markup { \sharp } -@end lilypond - - - - -@seealso - -Program reference: @internalsref{ScriptEvent}, and @internalsref{Script}. - -@refbugs - -These signs appear in the printed output but have no effect on the -MIDI rendering of the music. - - - - @@ -1673,4 +1566,414 @@ to be printed in a large font size. To print with a larger font, see @code{\setEasyHeads} +@node Other stuff +@section Other stuff + +This is a temporary placeholder for stuff that's being moved to Advanced. +It's just here so that somebody doesn't build the docs and then email me +to complain that I've lost some doc sections. :) + +@menu +* Aligning to cadenzas:: +* Stems:: +* Transpose:: +* Ottava brackets:: +* Time administration:: +* Controlling formatting of prefatory matter:: +* Setting automatic beam behavior:: +* Beam formatting:: +@end menu + + +@node Aligning to cadenzas +@subsection Aligning to cadenzas + + +In an orchestral context, cadenzas present a special problem: +when constructing a score that includes a cadenza, all other +instruments should skip just as many notes as the length of the +cadenza, otherwise they will start too soon or too late. + +A solution to this problem are the functions @code{mmrest-of-length} +and @code{skip-of-length}. These Scheme functions take a piece of music +as argument, and generate a @code{\skip} or multi-rest, exactly as +long as the piece. The use of @code{mmrest-of-length} is demonstrated +in the following example. + +@lilypond[verbatim,raggedright,quote] +cadenza = \relative c' { + c4 d8 << { e f g } \\ { d4. } >> + g4 f2 g4 g +} + +\new GrandStaff << + \new Staff { \cadenza c'4 } + \new Staff { + #(ly:export (mmrest-of-length cadenza)) + c'4 + } +>> +@end lilypond + + +@node Stems +@subsection Stems + +Whenever a note is found, a @internalsref{Stem} object is created +automatically. For whole notes and rests, they are also created but +made invisible. + +@refcommands + +@cindex @code{\stemUp} +@code{\stemUp}, +@cindex @code{\stemDown} +@code{\stemDown}, +@cindex @code{\stemNeutral} +@code{\stemNeutral}. + + +@node Transpose +@subsection Transpose +@cindex Transpose +@cindex transposition of pitches +@cindex @code{\transpose} + +A music expression can be transposed with @code{\transpose}. The +syntax is +@example +\transpose @var{from} @var{to} @var{musicexpr} +@end example + +This means that @var{musicexpr} is transposed by the interval between +the pitches @var{from} and @var{to}: any note with pitch @code{from} +is changed to @code{to}. + + +For example, consider a piece written in the key of D-major. If +this piece is a little too low for its performer, it can be +transposed up to E-major with +@example +\transpose d e @dots{} +@end example + +Consider a part written for violin (a C instrument). If +this part is to be played on the A clarinet, the following +transposition will produce the appropriate part + +@example +\transpose a c @dots{} +@end example + +@code{\transpose} distinguishes between enharmonic pitches: both +@code{\transpose c cis} or @code{\transpose c des} will transpose up +half a tone. The first version will print sharps and the second +version will print flats + +@lilypond[quote,raggedright,verbatim] +mus = { \key d \major cis d fis g } +\context Staff { + \clef "F" \mus + \clef "G" + \transpose c g' \mus + \transpose c f' \mus +} +@end lilypond + +@code{\transpose} may also be used to input written notes for a +transposing instrument. Pitches are normally entered into LilyPond +in C (or ``concert pitch''), but they may be entered in another +key. For example, when entering music for a B-flat trumpet which +begins on concert D, one would write + +@example +\transpose c bes @{ e4 @dots{} @} +@end example + +To print this music in B-flat again (ie producing a trumpet part, +instead of a concert pitch conductor's score) you would wrap the +existing music with another @code{transpose} + +@example +\transpose bes c @{ \transpose c bes @{ e4 @dots{} @} @} +@end example + + +@seealso + +Program reference: @internalsref{TransposedMusic}, and +@internalsref{UntransposableMusic}. + +@refbugs + +If you want to use both @code{\transpose} and @code{\relative}, +you must put @code{\transpose} outside of @code{\relative}, since +@code{\relative} will have no effect music that appears inside a +@code{\transpose}. + + +@node Ottava brackets +@subsection Ottava brackets + +`Ottava' brackets introduce an extra transposition of an octave for +the staff. They are created by invoking the function +@code{set-octavation} + +@cindex ottava +@cindex 15ma +@cindex octavation + +@lilypond[quote,raggedright,verbatim,fragment] +\relative c''' { + a2 b + #(set-octavation 1) + a b + #(set-octavation 0) + a b +} +@end lilypond + +The @code{set-octavation} function also takes -1 (for 8va bassa) and 2 +(for 15ma) as arguments. Internally the function sets the properties +@code{ottavation} (e.g., to @code{"8va"}) and +@code{centralCPosition}. For overriding the text of the bracket, set +@code{ottavation} after invoking @code{set-octavation}, i.e., + +@lilypond[quote,raggedright,verbatim] +{ + #(set-octavation 1) + \set Staff.ottavation = #"8" + c''' +} +@end lilypond + +@seealso + +Program reference: @internalsref{OttavaBracket}. + +Examples: @inputfileref{input/@/regression,ottava@/.ly}, +@inputfileref{input/@/regression,ottava@/-broken@/.ly}. + +@refbugs + +@code{set-octavation} will get confused when clef changes happen +during an octavation bracket. + + +@node Time administration +@subsection Time administration + +Time is administered by the @internalsref{Time_signature_engraver}, +which usually lives in the @internalsref{Score} context. +The bookkeeping deals with the following variables + +@table @code +@item currentBarNumber +The measure number. + +@item measureLength +The length of the measures in the current time signature. For a 4/4 +time this is@tie{}1, and for 6/8 it is 3/4. + +@item measurePosition +The point within the measure where we currently are. This quantity +is reset to@tie{}0 whenever it exceeds @code{measureLength}. When that +happens, @code{currentBarNumber} is incremented. + +@item timing +If set to true, the above variables are updated for every time +step. When set to false, the engraver stays in the current measure +indefinitely. +@end table + +Timing can be changed by setting any of these variables explicitly. +In the next example, the 4/4 time signature is printed, but +@code{measureLength} is set to 5/4. After a while, the measure is +shortened by 1/8, by setting @code{measurePosition} to 7/8 at 2/4 +in the measure, so the next bar line will fall at 2/4 + 3/8. The +3/8 arises because 5/4 normally has 10/8, but we have manually +set the measure position to be 7/8 and 10/8 - 7/8 = 3/8. + +@lilypond[quote,raggedright,verbatim,relative,fragment] +\set Score.measureLength = #(ly:make-moment 5 4) +c1 c4 +c1 c4 +c4 c4 +\set Score.measurePosition = #(ly:make-moment 7 8) +b8 b b +c4 c1 +@end lilypond + + +@node Controlling formatting of prefatory matter +@subsection Controlling formatting of prefatory matter + +@c This section will be moved to somewhere else soon. -gp +This example demonstrates how to place prefatory matter +(such as the clef and key signature) at the end of a line. + +@lilypond[quote,verbatim] +\transpose c c' { + \override Staff.Clef + #'break-visibility = #end-of-line-visible + \override Staff.KeySignature + #'break-visibility = #end-of-line-visible + \set Staff.explicitClefVisibility = #end-of-line-visible + \set Staff.explicitKeySignatureVisibility = #end-of-line-visible + + % We want the time sig to take space, otherwise there is not + % enough white at the start of the line. + + \override Staff.TimeSignature #'transparent = ##t + \set Score.defaultBarType = #"empty" + + c1 d e f g a b c + \key d \major + \break + + % see above. + \time 4/4 + + d e fis g a b cis d + \key g \major + \break + \time 4/4 +} +@end lilypond + + +@node Setting automatic beam behavior +@subsection Setting automatic beam behavior + +@cindex @code{autoBeamSettings} +@cindex @code{(end * * * *)} +@cindex @code{(begin * * * *)} +@cindex automatic beams, tuning +@cindex tuning automatic beaming + +@c [TODO: use \applycontext] + +In normal time signatures, automatic beams can start on any note but can +only end in a few positions within the measure: beams can end on a beat, +or at durations specified by the properties in +@code{autoBeamSettings}. The defaults for @code{autoBeamSettings} +are defined in @file{scm/@/auto@/-beam@/.scm}. + +The value of @code{autoBeamSettings} is changed with three functions, +@example +#(override-auto-beam-setting + '(@var{be} @var{p} @var{q} @var{n} @var{m}) @var{a} @var{b} + [@var{context}]) +#(score-override-auto-beam-setting + '(@var{be} @var{p} @var{q} @var{n} @var{m}) @var{a} @var{b}) +#(revert-auto-beam-setting '(@var{be} @var{p} @var{q} @var{n} @var{m}) + [@var{context}]) +@end example +Here, @var{be} is the symbol @code{begin} or @code{end}, and +@var{context} is an optional context (default: @code{'Voice}). It +determines whether the rule applies to begin or end-points. The +quantity @var{p}/@var{q} refers to the length of the beamed notes (and +`@code{* *}' designates notes of any length), @var{n}/@var{M} refers +to a time signature (wildcards `@code{* *}' may be entered to +designate all time signatures), @var{a}/@var{b} is a duration. By +default, this command changes settings for the current voice. It is +also possible to adjust settings at higher contexts, by adding a +@var{context} argument. @code{score-override-auto-beam-setting} is +equal to @code{override-auto-beam-setting} with the argument +@var{context} set to @code{'Score}. + +For example, if automatic beams should end on every quarter note, use +the following +@example +#(override-auto-beam-setting '(end * * * *) 1 4 'Staff) +@end example +Since the duration of a quarter note is 1/4 of a whole note, it is +entered as @code{(ly:make-moment 1 4)}. + +The same syntax can be used to specify beam starting points. In this +example, automatic beams can only end on a dotted quarter note +@example +#(override-auto-beam-setting '(end * * * *) 3 8) +@end example +In 4/4 time signature, this means that automatic beams could end only on +3/8 and on the fourth beat of the measure (after 3/4, that is 2 times +3/8, has passed within the measure). + +Rules can also be restricted to specific time signatures. A rule that +should only be applied in @var{N}/@var{M} time signature is formed by +replacing the second asterisks by @var{N} and @var{M}. For example, a +rule for 6/8 time exclusively looks like +@example +#(override-auto-beam-setting '(begin * * 6 8) @dots{}) +@end example + +If a rule should be to applied only to certain types of beams, use the +first pair of asterisks. Beams are classified according to the +shortest note they contain. For a beam ending rule that only applies +to beams with 32nd notes (and no shorter notes), use @code{(end 1 32 * +*)}. + +@cindex automatic beam generation +@cindex autobeam +@cindex @code{autoBeaming} +@cindex lyrics + +If beams are used to indicate melismata in songs, then automatic +beaming should be switched off. This is done by setting +@code{autoBeaming} to @code{#f}. + +@refcommands + +@cindex @code{\autoBeamOff} +@code{\autoBeamOff}, +@cindex @code{\autoBeamOn} +@code{\autoBeamOn}. + + +@refbugs + +If a score ends while an automatic beam has not been ended and is +still accepting notes, this last beam will not be typeset at all. The +same holds polyphonic voices, entered with @code{<< @dots{} \\ @dots{} +>>}. If a polyphonic voice ends while an automatic beam is still +accepting notes, it is not typeset. + +The rules for ending a beam depend on the shortest note in a beam. +So, while it is possible to have different ending rules for eight +beams and sixteenth beams, a beam that contains both eight and +sixteenth notes will use the rules for the sixteenth beam. + +In the example below, the autobeamer makes eighth beams and sixteenth +end at three eighths. The third beam can only be corrected by +specifying manual beaming. + +@lilypond[quote,raggedright,fragment,relative=1] +#(override-auto-beam-setting '(end * * * *) 3 8) +% rather show case where it goes wrong +%\time 12/8 c'8 c c c16 c c c c c c[ c c c] c8[ c] c4 +\time 12/8 c'8 c c c16 c c c c c c c c c c8 c c4 +@end lilypond +It is not possible to specify beaming parameters that act differently in +different parts of a measure. This means that it is not possible to use +automatic beaming in irregular meters such as @code{5/8}. + +@node Beam formatting +@subsection Beam formatting + + +When a beam falls in the middle of the staff, the beams point normally +down. However, this behaviour can be altered with the +@code{neutral-direction} property. + + +@lilypond[quote,raggedright,relative=2,fragment,verbatim] +{ + b8[ b] + \override Beam #'neutral-direction = #-1 + b[ b] + \override Beam #'neutral-direction = #1 + b[ b] +} +@end lilypond + -- 2.39.5