X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Feditorial.itely;h=96f2786da8551687663125e7fcc70f60254fc5e8;hb=41e45dd730c075e78065dfa78e5e54be664d905e;hp=75b4ca572c852c196fec66e09babc607df7570e7;hpb=e3196be0cd6570bf204ea7353a6710634e83b61f;p=lilypond.git diff --git a/Documentation/user/editorial.itely b/Documentation/user/editorial.itely index 75b4ca572c..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:: @@ -32,45 +36,51 @@ @end menu @node Selecting notation font size -@subsubsection Selecting notation font size +@unnumberedsubsubsec Selecting notation font size @cindex font size @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. +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] -c4 -\set fontSize = #-4 -c f -\set fontSize = #3 -g8 a +\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. +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] -c4 +\set fontSize = #3 +c4.-> d8---3 \override NoteHead #'font-size = #-4 -c f -\override NoteHead #'font-size = #3 -g8 a +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,30 +91,34 @@ 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 -@subsubsection Fingering instructions +@unnumberedsubsubsec Fingering instructions @cindex fingering @cindex finger change @@ -116,7 +130,7 @@ Fingering instructions can be entered using c4-1 d-2 f-4 e-3 @end lilypond -Use markup texts for finger changes. +Markup texts may be used for finger changes. @lilypond[quote,verbatim,ragged-right,fragment,relative=2] c4-1 d-2 f-4 c^\markup { \finger "2 - 3" } @@ -128,7 +142,7 @@ 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 @@ -141,36 +155,29 @@ chord by adding them after the pitches. < 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 -@code{fingeringOrientations} are used to control where the fingering -numbers are placed. +@lilypondfile[verbatim,lilyquote,ragged-right,texidoc] +{controlling-the-placement-of-chord-fingerings.ly} -@lilypond[quote,verbatim,ragged-right,fragment,relative=2] -\set fingeringOrientations = #'(left) - 4 -\set fingeringOrientations = #'(down) - -\set fingeringOrientations = #'(right) - -\set fingeringOrientations = #'(up) - -\set fingeringOrientations = #'(left down) - 2 -\set fingeringOrientations = #'(up right down) - -@end lilypond @seealso -Snippets: @lsrdir{Editorial,Editorial-annotations}. +Notation Reference: +@ref{Controlling direction and placement} -Internals Reference: @internalsref{Fingering}. +Snippets: +@lsrdir{Editorial,Editorial-annotations}. + +Internals Reference: +@internalsref{Fingering}. @node Hidden notes -@subsubsection Hidden notes +@unnumberedsubsubsec Hidden notes @cindex Hidden notes @cindex Invisible notes @@ -182,24 +189,29 @@ 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 -g4 a +g a \hideNotes b \unHideNotes c @end lilypond +@predefined + +@code{\hideNotes}, @code{\unHideNotes} + @seealso -Snippets: @lsrdir{Editorial,Editorial-annotations}. +Snippets: +@lsrdir{Editorial,Editorial-annotations}. @node Coloring objects -@subsubsection Coloring objects +@unnumberedsubsubsec Coloring objects @cindex colored objects @cindex colors @@ -223,97 +235,76 @@ e @cindex x11-color 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 +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. -@example -\override Beam #'color = #(x11-color 'MediumTurquoise) -@end example +If @code{x11-color} cannot make sense of the parameter then the +color returned defaults to black. -or a string - -@example -\override Beam #'color = #(x11-color "MediumTurquoise") -@end example - -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 +@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. -@lilypond[quote,ragged-right,verbatim] -{ - \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2) - \set Staff.instrumentName = \markup { - \with-color #(x11-color 'navy) "Clarinet" - } - \time 4/4 - - %black - \override Stem #'color = #(rgb-color 0 0 0) - c4 - % white - \override Stem #'color = #(rgb-color 1 1 1) - d - % dark blue - \override Stem #'color = #(rgb-color 0 0 0.5) - e +@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 -Notation Reference: @ref{List of colors}, @ref{Objects connected to +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 i.e. a web -browser might not display a difference between 'LimeGreen and -'ForestGreen. For web use normal colors are recommended. (#blue, -#green, #red) +Snippets: +@lsrdir{Editorial,Editorial-annotations}. +@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 -@subsubsection Parentheses +@unnumberedsubsubsec Parentheses @cindex ghost notes @cindex notes, ghost @@ -321,42 +312,35 @@ for details. @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 -. -d g -< - c - \parenthesize fis -> -@end lilypond +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-> -This only functions inside chords, to parenthesize a single note it -must be enclosed with @code{<>} as if it is a chord. +@lilypond[quote,relative=2,fragment,verbatim,ragged-right] +c2 < \parenthesize d> +@end lilypond -@example -< \parenthesize NOTE> -@end example +Non-note objects may be parenthesized as well. -@lilypond[relative=2,fragment,verbatim,ragged-right] -c4 -<\parenthesize d> -g -<\parenthesize d> +@lilypond[quote,relative=2,fragment,verbatim,ragged-right] +< c d g >2-\parenthesize -. d @end lilypond @seealso -Snippets: @lsrdir{Editorial,Editorial-annotations}. +Snippets: +@lsrdir{Editorial,Editorial-annotations}. + +@knownissues + +Rests cannot be parenthesized. @node Stems -@subsubsection Stems +@unnumberedsubsubsec Stems @cindex stem @@ -364,7 +348,7 @@ 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}, @@ -374,31 +358,29 @@ made invisible. @code{\stemNeutral}. -@commonprop +@snippets @cindex stem, direction @cindex stem, up @cindex stem, down @cindex stem, neutral -To change the direction of stems on the center line of the staff, use - -@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}. +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:: @@ -407,86 +389,97 @@ Snippets: @lsrdir{Editorial,Editorial-annotations}. @end menu @node Balloon help -@subsubsection Balloon help +@unnumberedsubsubsec Balloon help 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 There are two music functions, @code{balloonGrobText} and -@code{balloonText}; the former takes the name of the grob to adorn, -while the latter may be used as an articulation on a note. The other -arguments are the offset and the text of the label. +@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 -Snippets: @lsrdir{Editorial,Editorial-annotations}. +Snippets: +@lsrdir{Editorial,Editorial-annotations}. -Internals Reference: @internalsref{text-balloon-interface}. +Internals Reference: +@internalsref{text-balloon-interface}. @node Grid lines -@subsubsection Grid lines +@unnumberedsubsubsec Grid lines 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 + +@lilypondfile[verbatim,lilyquote,ragged-right,texidoc] +{grid-lines-changing-their-appearance.ly} + + @seealso -Snippets: @lsrdir{Editorial,Editorial-annotations}. +Snippets: +@lsrdir{Editorial,Editorial-annotations}. @node Analysis brackets -@subsubsection Analysis brackets +@unnumberedsubsubsec Analysis brackets @cindex brackets @cindex phrasing brackets @@ -494,31 +487,43 @@ Snippets: @lsrdir{Editorial,Editorial-annotations}. @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 @code{Horizontal_bracket_engraver} to -the @code{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 +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 -Snippets: @lsrdir{Editorial,Editorial-annotations}. +Snippets: +@lsrdir{Editorial,Editorial-annotations}. -Internals Reference: @internalsref{HorizontalBracket}, -@internalsref{Horizontal_bracket_engraver}, @internalsref{Staff}. +Internals Reference: +@internalsref{HorizontalBracket}, +@internalsref{Horizontal_bracket_engraver}, +@internalsref{Staff}.