X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Feditorial.itely;h=96f2786da8551687663125e7fcc70f60254fc5e8;hb=18c8f740f67e6063de22296054f78c6218f8d224;hp=11afc1a0f749dc0d61dcff10332c22b02ed72560;hpb=970c4b3f5defca050ab4589ab2f9c81a193af6f1;p=lilypond.git diff --git a/Documentation/user/editorial.itely b/Documentation/user/editorial.itely index 11afc1a0f7..96f2786da8 100644 --- a/Documentation/user/editorial.itely +++ b/Documentation/user/editorial.itely @@ -9,8 +9,10 @@ @node Editorial annotations @section Editorial annotations -@lilypondfile[ragged-right,line-width=16\cm,staffsize=16,quote] -{editorial-headword.ly} +@lilypondfile[quote]{editorial-headword.ly} + +This section discusses the various ways to change the appearance of +notes and add analysis or educational emphasis. @menu * Inside the staff:: @@ -21,6 +23,8 @@ @node Inside the staff @subsection Inside the staff +This section discusses how to add emphasis to elements that are +inside the staff. @menu * Selecting notation font size:: @@ -38,39 +42,45 @@ @cindex font size, selecting @cindex selecting font size -The easiest method of setting the font size of any context is by -setting the @code{fontSize} property. - -@lilypond[quote,fragment,relative=1,verbatim] -c8 -\set fontSize = #-4 -c f -\set fontSize = #3 -g +The font size of notation elements may be altered. It does not +change the size of variable symbols, such as beams or slurs. + +@lilypond[quote,fragment,relative=2,verbatim,ragged-right] +\huge +c4.-> d8---3 +\large +c4.-> d8---3 +\normalsize +c4.-> d8---3 +\small +c4.-> d8---3 +\tiny +c4.-> d8---3 +\normalsize +c2 @end lilypond -@noindent -It does not change the size of variable symbols, such as beams or -slurs. - @cindex font size scaling -Internally, the @code{fontSize} context property will cause the -@code{font-size} property to be set in all layout objects. The -value of @code{font-size} is a number indicating the size relative -to the standard size for the current staff height. Each step up -is an increase of approximately 12% of the font size. Six steps -is exactly a factor two. The Scheme function @code{magstep} -converts a @code{font-size} number to a scaling factor. The -@code{font-size} property can also be set directly, so that only -certain layout objects are affected. - -@lilypond[quote,fragment,relative=1,verbatim] -c8 +Internally, this sets the @code{fontSize} property. This in turns +causes the @code{font-size} property to be set in all layout +objects. The value of @code{font-size} is a number indicating the +size relative to the standard size for the current staff height. +Each step up is an increase of approximately 12% of the font size. +Six steps is exactly a factor two. The Scheme function +@code{magstep} converts a @code{font-size} number to a scaling +factor. The @code{font-size} property can also be set directly, +so that only certain layout objects are affected. + +@lilypond[quote,fragment,relative=2,verbatim,ragged-right] +\set fontSize = #3 +c4.-> d8---3 \override NoteHead #'font-size = #-4 -c f -\override NoteHead #'font-size = #3 -g +c4.-> d8---3 +\override Script #'font-size = #2 +c4.-> d8---3 +\override Stem #'font-size = #-5 +c4.-> d8---3 @end lilypond @cindex standard font size @@ -81,26 +91,30 @@ closest to the desired size. The standard font size (for @code{font-size} equals 0), depends on the standard staff height. For a 20pt staff, a 10pt font is selected. -The @code{font-size} property can only be set on layout objects that -use fonts. These are the ones supporting the @code{font-interface} -layout interface. +The @code{font-size} property can only be set on layout objects +that use fonts. These are the ones supporting the +@code{font-interface} layout interface. -@refcommands - -The following commands set @code{fontSize} for the current voice: +@predefined @funindex \tiny @code{\tiny}, @funindex \small @code{\small}, @funindex \normalsize -@code{\normalsize}. +@code{\normalsize}, +@funindex \large +@code{\large}, +@funindex \huge +@code{\huge}. @seealso -Snippets: @lsrdir{Editorial,Editorial-annotations}. +Snippets: +@lsrdir{Editorial,Editorial-annotations}. -Internals Reference: @internalsref{font-interface}. +Internals Reference: +@internalsref{font-interface}. @node Fingering instructions @@ -110,68 +124,56 @@ Internals Reference: @internalsref{font-interface}. @cindex finger change Fingering instructions can be entered using +@var{note}-@var{digit}: -@example -@var{note}-@var{digit} -@end example +@lilypond[quote,verbatim,ragged-right,fragment,relative=2] +c4-1 d-2 f-4 e-3 +@end lilypond -For finger changes, use markup texts +Markup texts may be used for finger changes. -@lilypond[quote,verbatim,ragged-right,fragment,relative=1] -c4-1 c-2 c-3 c-4 -c^\markup { \finger "2 - 3" } +@lilypond[quote,verbatim,ragged-right,fragment,relative=2] +c4-1 d-2 f-4 c^\markup { \finger "2 - 3" } @end lilypond @cindex thumb-script - -You can use the thumb-script to indicate that a note should be -played with the thumb (e.g., in cello music) +You can use the thumb-script (e.g., in cello music)to indicate that a +note should be played with the thumb. @lilypond[quote,verbatim,ragged-right,fragment,relative=2] -8 +2 @end lilypond @cindex fingering chords @cindex chords, fingering Fingerings for chords can also be added to individual notes of the -chord by adding them after the pitches +chord by adding them after the pitches. @lilypond[quote,verbatim,ragged-right,fragment,relative=2] -< c-1 e-2 g-3 b-5 >4 +< c-1 e-2 g-3 b-5 >2 < d-1 f-2 a-3 c-5 > @end lilypond +Fingering instructions may be manually placed above or below the +staff, see @ref{Controlling direction and placement}. -@commonprop +@snippets -You may exercise greater control over fingering chords by setting -@code{fingeringOrientations} - -@lilypond[quote,verbatim,ragged-right,fragment,relative=1] -\set fingeringOrientations = #'(left down) - 4 -\set fingeringOrientations = #'(up right down) - 4 -@end lilypond - -Using this feature, it is also possible to put fingering -instructions very close to note heads in monophonic music, - -@lilypond[verbatim,ragged-right,quote,fragment] -\set fingeringOrientations = #'(right) -4 -@end lilypond +@lilypondfile[verbatim,lilyquote,ragged-right,texidoc] +{controlling-the-placement-of-chord-fingerings.ly} @seealso -Snippets: @lsrdir{Editorial,Editorial-annotations}. +Notation Reference: +@ref{Controlling direction and placement} -Internals Reference: @internalsref{Fingering}. - -Examples: @c @lsr{expressive,fingering-chords.ly} +Snippets: +@lsrdir{Editorial,Editorial-annotations}. +Internals Reference: +@internalsref{Fingering}. @node Hidden notes @@ -180,7 +182,6 @@ Examples: @c @lsr{expressive,fingering-chords.ly} @cindex Hidden notes @cindex Invisible notes @cindex Transparent notes - @funindex \hideNotes @funindex \unHideNotes @@ -188,21 +189,41 @@ Hidden (or invisible or transparent) notes can be useful in preparing theory or composition exercises. @lilypond[quote,ragged-right,verbatim,relative=2,fragment] -c4 d4 +c4 d \hideNotes -e4 f4 +e4 f +\unHideNotes +g a +\hideNotes +b \unHideNotes -g4 a +c @end lilypond +@predefined + +@code{\hideNotes}, @code{\unHideNotes} + +@seealso + +Snippets: +@lsrdir{Editorial,Editorial-annotations}. + @node Coloring objects @unnumberedsubsubsec Coloring objects +@cindex colored objects +@cindex colors +@cindex coloring objects +@cindex colored notes +@cindex coloring notes +@cindex notes, colored + Individual objects may be assigned colors. You may use the color names listed in the @ref{List of colors}. -@lilypond[quote,ragged-right,verbatim,fragment,relative=1] +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] \override NoteHead #'color = #red c4 c \override NoteHead #'color = #(x11-color 'LimeGreen) @@ -211,80 +232,75 @@ d e @end lilypond -The full range of colors defined for X11 can be accessed by using -the Scheme function x11-color. The function takes one argument -that can be a symbol - -@example -\override Beam #'color = #(x11-color 'MediumTurquoise) -@end example - -or a string - -@example -\override Beam #'color = #(x11-color "MediumTurquoise") -@end example +@cindex x11-color -The first form is quicker to write and is more efficient. -However, using the second form it is possible to access X11 colors -by the multi-word form of its name +The full range of colors defined for X11 can be accessed by using +the Scheme function @code{x11-color}. The function takes one +argument; this can be a symbol in the form @var{'FooBar} or a +string in the form @var{"FooBar"}. The first form is quicker to +write and is more efficient. However, using the second form it is +possible to access X11 colors by the multi-word form of its name. + +If @code{x11-color} cannot make sense of the parameter then the +color returned defaults to black. + +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +\override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2) +\set Staff.instrumentName = \markup { + \with-color #(x11-color 'navy) "Clarinet" +} -@example +gis8 a \override Beam #'color = #(x11-color "medium turquoise") -@end example - -If x11-color cannot make sense of the parameter then the color -returned defaults to black. It should be obvious from the final -score that something is wrong. - -This example illustrates the use of x11-color. Notice that the -stem color remains black after being set to (x11-color 'Boggle), -which is deliberate nonsense. - -@lilypond[quote,ragged-right,verbatim] -{ - \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2) - \set Staff.instrumentName = \markup { - \with-color #(x11-color 'navy) "Clarinet" - } - \time 2/4 - gis''8 a'' - \override Beam #'color = #(x11-color "medium turquoise") - gis'' a'' - \override NoteHead #'color = #(x11-color "LimeGreen") - gis'' a'' - \override Stem #'color = #(x11-color 'Boggle) - gis'' a'' -} +gis a +\override Accidental #'color = #(x11-color 'DarkRed) +gis a +\override NoteHead #'color = #(x11-color "LimeGreen") +gis a +% this is deliberate nonsense; note that the stems remain black +\override Stem #'color = #(x11-color 'Boggle) +b2 cis @end lilypond +You can get exact RGB colors by specifying the rgb-color number. -TODO -you can get exact RGB colors by specifying - -% black +@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +\override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2) +\set Staff.instrumentName = \markup { + \with-color #(x11-color 'navy) "Clarinet" +} + +%black \override Stem #'color = #(rgb-color 0 0 0) +gis8 a % white \override Stem #'color = #(rgb-color 1 1 1) +gis8 a % dark blue \override Stem #'color = #(rgb-color 0 0 0.5) - +gis4 a +@end lilypond @seealso -Appendix: @ref{List of colors}. +Notation Reference: +@ref{List of colors}, @ref{Objects connected to +the input}. +Snippets: +@lsrdir{Editorial,Editorial-annotations}. -@refbugs -Not all x11 colors are distinguishable in a web browser. For web -use normal colors are recommended. - +@knownissues An x11 color is not necessarily exactly the same shade as a -similarly named normal color. +similarly named normal color. + +Not all x11 colors are distinguishable in a web browser i.e. a web browser +might not display a difference between 'LimeGreen and 'ForestGreen. For +web use normal colors are recommended (i.e. #blue, #green, #red). + Notes in a chord cannot be colored with @code{\override}; use -@code{\tweak} instead. See @ref{Objects connected to the input}, -for details. +@code{\tweak} instead, see @ref{Objects connected to the input}. @node Parentheses @@ -293,34 +309,46 @@ for details. @cindex ghost notes @cindex notes, ghost @cindex notes, parenthesized +@cindex parentheses Objects may be parenthesized by prefixing @code{\parenthesize} to -the music event, - -@lilypond[relative=2,fragment,verbatim,ragged-right] -< - c - \parenthesize d - g ->4-\parenthesize -. +the music event. This only functions inside chords; to +parenthesize a single note it must be enclosed with @code{<>} as +if it is a chord. + +FIXME: after 2.11.44 is out, +@c \parenthesize c4-. \parenthesize r4 \parenthesize 4-> + +@lilypond[quote,relative=2,fragment,verbatim,ragged-right] +c2 < \parenthesize d> @end lilypond -This only functions inside chords, to parenthesize a single note it -must be enclosed with @code{<>} as if it is a chord. +Non-note objects may be parenthesized as well. + +@lilypond[quote,relative=2,fragment,verbatim,ragged-right] +< c d g >2-\parenthesize -. d +@end lilypond + +@seealso + +Snippets: +@lsrdir{Editorial,Editorial-annotations}. -@example -< \parenthesize NOTE> -@end example +@knownissues + +Rests cannot be parenthesized. @node Stems @unnumberedsubsubsec 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. +@cindex stem + +Whenever a note is found, a @code{Stem} object is created +automatically. For whole notes and rests, they are also created but +made invisible. -@refcommands +@predefined @funindex \stemUp @code{\stemUp}, @@ -330,27 +358,33 @@ but made invisible. @code{\stemNeutral}. -@commonprop +@snippets -To change the direction of stems on the center line of the staff, use +@cindex stem, direction +@cindex stem, up +@cindex stem, down +@cindex stem, neutral -@lilypond[quote,ragged-right,fragment,relative=2,verbatim] -a4 b c b -\override Stem #'neutral-direction = #up -a4 b c b -\override Stem #'neutral-direction = #down -a4 b c b -@end lilypond +@lilypondfile[verbatim,lilyquote,ragged-right,texidoc] +{default-direction-of-stems-on-the-center-line-of-the-staff.ly} + +@seealso +Notation Reference: +@ref{Controlling direction and placement}. + +Snippets: +@lsrdir{Editorial,Editorial-annotations}. @node Outside the staff @subsection Outside the staff +This section discusses how to add emphasis to elements in the staff +from outside of the staff. @menu * Balloon help:: * Grid lines:: -* Blank music sheet:: * Analysis brackets:: @end menu @@ -361,28 +395,32 @@ Elements of notation can be marked and named with the help of a square balloon. The primary purpose of this feature is to explain notation. -The following example demonstrates its use. - @lilypond[quote,verbatim,fragment,ragged-right,relative=2] \new Voice \with { \consists "Balloon_engraver" } { \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" } - 8 + a8 + \balloonGrobText #'Rest #' (-4 . -4) \markup { "I'm a rest" } + r + 2. } @end lilypond -@noindent -There are two music functions, @code{balloonText} and -@code{balloonGrobText}. The latter takes the name of the grob to -adorn, while the former may be used as an articulation on a note. -The other arguments are the offset and the text of the label. +There are two music functions, @code{balloonGrobText} and +@code{balloonText}; The former is used like @code{\once \override} to +attach text to any grob, and the latter is used like @code{ \tweak}, +typically within chords, to attach text to an individual note. @cindex balloon @cindex notation, explaining @seealso -Internals Reference: @internalsref{text-balloon-interface}. +Snippets: +@lsrdir{Editorial,Editorial-annotations}. + +Internals Reference: +@internalsref{text-balloon-interface}. @node Grid lines @@ -391,73 +429,53 @@ Internals Reference: @internalsref{text-balloon-interface}. Vertical lines can be drawn between staves synchronized with the notes. -@lilypond[ragged-right,quote,verbatim] +@lilypond[quote,verbatim,ragged-right] \layout { \context { \Staff - \consists "Grid_point_engraver" %% sets of grid + % sets up grids + \consists "Grid_point_engraver" + % this sets the grid interval to 1 quarternote (crotchet) gridInterval = #(ly:make-moment 1 4) - } + } } \new Score \with { + % by default this centers grid lines horizontally below and to the + % left side of the notehead, the grid lines extend from + % the middle lines of each staff \consists "Grid_line_span_engraver" - %% centers grid lines horizontally below note heads - \override NoteColumn #'X-offset = #-0.5 -} + } \new ChoirStaff << \new Staff { - \stemUp - \relative { - c'4. d8 e8 f g4 + \relative c'' { + \stemUp + c4. d8 e8 f g4 } } \new Staff { - %% centers grid lines vertically - \override Score.GridLine #'extra-offset = #'( 0.0 . 1.0 ) - \stemDown \clef bass \relative c { + \stemDown c4 g' f e } } >> @end lilypond -Snippets: @lsrdir{Editorial,Editorial-annotations}. +@snippets +@lilypondfile[verbatim,lilyquote,ragged-right,texidoc] +{grid-lines-changing-their-appearance.ly} -@node Blank music sheet -@unnumberedsubsubsec Blank music sheet -@cindex Sheet music, empty -@cindex Staves, blank sheet +@seealso -A blank music sheet can be produced also by using invisible notes, -and removing @code{Bar_number_engraver}. +Snippets: +@lsrdir{Editorial,Editorial-annotations}. -@lilypond[quote,verbatim] -\layout{ indent = #0 } -emptymusic = { - \repeat unfold 2 % Change this for more lines. - { s1\break } - \bar "|." -} -\new Score \with { - \override TimeSignature #'transparent = ##t -% un-comment this line if desired -% \override Clef #'transparent = ##t - defaultBarType = #"" - \remove Bar_number_engraver -} << - -% modify these to get the staves you want - \new Staff \emptymusic - \new TabStaff \emptymusic ->> -@end lilypond @node Analysis brackets @@ -468,29 +486,44 @@ emptymusic = { @cindex musicological analysis @cindex note grouping bracket -Brackets are used in musical analysis to indicate structure in -musical pieces. LilyPond supports a simple form of nested -horizontal brackets. To use this, add the -@internalsref{Horizontal_bracket_engraver} to the -@internalsref{Staff} context. A bracket is started with -@code{\startGroup} and closed with @code{\stopGroup}. - -@lilypond[quote,ragged-right,verbatim] -\score { - \relative c'' { - c4\startGroup\startGroup - c4\stopGroup - c4\startGroup - c4\stopGroup\stopGroup +Brackets are used in musical analysis to indicate structure in musical +pieces. LilyPond supports a simple form of horizontal brackets. + +@lilypond[quote,verbatim,ragged-right] +\layout { + \context { + \Staff \consists "Horizontal_bracket_engraver" } - \layout { - \context { - \Staff \consists "Horizontal_bracket_engraver" -}}} +} +\relative c'' { + c2\startGroup + d\stopGroup +} +@end lilypond + +Analysis brackets may be nested. + +@lilypond[quote,verbatim,ragged-right] +\layout { + \context { + \Staff \consists "Horizontal_bracket_engraver" + } +} +\relative c'' { + c4\startGroup\startGroup + d4\stopGroup + e4\startGroup + d4\stopGroup\stopGroup +} @end lilypond @seealso -Internals Reference: @internalsref{HorizontalBracket}. +Snippets: +@lsrdir{Editorial,Editorial-annotations}. +Internals Reference: +@internalsref{HorizontalBracket}, +@internalsref{Horizontal_bracket_engraver}, +@internalsref{Staff}.