X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Feditorial.itely;h=3f04aff558f9347e5836345dc8efe680debd80d3;hb=1eb0a25104a5bef7a6dc0ea9093f73cf3ba66fd5;hp=99f32bff59fc57ab23631a4868533d68b0d142e4;hpb=2a7a24ea2525a33d14b020e318d7f7054d1334d1;p=lilypond.git diff --git a/Documentation/user/editorial.itely b/Documentation/user/editorial.itely index 99f32bff59..3f04aff558 100644 --- a/Documentation/user/editorial.itely +++ b/Documentation/user/editorial.itely @@ -6,11 +6,15 @@ version that you are working on. See TRANSLATION for details. @end ignore +@c \version "2.11.38" + @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 +25,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,79 +38,95 @@ @end menu @node Selecting notation font size -@subsubsection 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. - -@lilypond[quote,fragment,relative=2,verbatim,ragged-right] -c4 -\set fontSize = #-4 -c f -\set fontSize = #3 -g8 a +@unnumberedsubsubsec Selecting notation font size + +@cindex font size (notation) +@cindex selecting font size (notation) + +The font size of notation elements may be altered. It does not +change the size of variable symbols, such as beams or slurs. + +@warning{For font sizes of text, see +@ref{Common markup commands}.} + +@lilypond[verbatim,quote,relative=2] +\huge +c4.-> d8---3 +\large +c4.-> d8---3 +\normalsize +c4.-> d8---3 +\small +c4.-> d8---3 +\tiny +c4.-> d8---3 +\teeny +c4.-> d8---3 @end lilypond -@noindent -It does not change the size of variable symbols, such as beams or -slurs. +@cindex font size (notation) scaling -@cindex font size scaling +Internally, this sets the @code{fontSize} property. This in turn +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 of 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, 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=2,verbatim,ragged-right] -c4 +@lilypond[verbatim,quote,relative=2] +\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 -@cindex font size, standard +@cindex standard font size (notation) +@cindex font size (notation), standard Font size changes are achieved by scaling the design size that is closest to the desired size. The standard font size (for -@code{font-size} equals 0), depends on the standard staff height. +@w{@code{font-size = #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. @predefined -The following commands set @code{fontSize} for the current voice: - +@funindex \teeny +@code{\teeny}, @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: +@rlsr{Editorial annotations}. -Internals Reference: @internalsref{font-interface}. +Internals Reference: +@rinternals{fontSize}, +@rinternals{font-size}, +@rinternals{font-interface}. @node Fingering instructions -@subsubsection Fingering instructions +@unnumberedsubsubsec Fingering instructions @cindex fingering @cindex finger change @@ -112,22 +134,22 @@ Internals Reference: @internalsref{font-interface}. Fingering instructions can be entered using @var{note}-@var{digit}: -@lilypond[quote,verbatim,ragged-right,fragment,relative=2] +@lilypond[verbatim,quote,relative=2] 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] +@lilypond[verbatim,quote,relative=2] c4-1 d-2 f-4 c^\markup { \finger "2 - 3" } @end lilypond @cindex thumb-script -You can use the thumb-script (e.g., in cello music)to indicate that a -note should be played with the thumb. +A thumb-script can be added (e.g., in cello music) to indicate +that a note should be played with the thumb. -@lilypond[quote,verbatim,ragged-right,fragment,relative=2] +@lilypond[verbatim,quote,relative=2] 2 @end lilypond @@ -137,51 +159,48 @@ note should be played with the thumb. Fingerings for chords can also be added to individual notes of the chord by adding them after the pitches. -@lilypond[quote,verbatim,ragged-right,fragment,relative=2] -< c-1 e-2 g-3 b-5 >2 < d-1 f-2 a-3 c-5 > +@lilypond[verbatim,quote,relative=2] +2 @end lilypond +Fingering instructions may be manually placed above or below the +staff, see @ref{Direction and placement}. @snippets -@code{fingeringOrientations} are used to control where the fingering -numbers are placed. - -@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 +@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle] +{controlling-the-placement-of-chord-fingerings.ly} + @seealso -Snippets: @lsrdir{Editorial,Editorial-annotations}. +Notation Reference: +@ref{Direction and placement} -Internals Reference: @internalsref{Fingering}. +Snippets: +@rlsr{Editorial annotations}. + +Internals Reference: +@rinternals{FingeringEvent}, +@rinternals{fingering-event}, +@rinternals{Fingering_engraver}, +@rinternals{New_fingering_engraver}, +@rinternals{Fingering}. @node Hidden notes -@subsubsection Hidden notes +@unnumberedsubsubsec Hidden notes -@cindex Hidden notes -@cindex Invisible notes -@cindex Transparent notes +@cindex hidden notes +@cindex invisible notes +@cindex transparent notes @funindex \hideNotes @funindex \unHideNotes Hidden (or invisible or transparent) notes can be useful in preparing theory or composition exercises. -@lilypond[quote,ragged-right,verbatim,relative=2,fragment] +@lilypond[verbatim,quote,relative=2] c4 d \hideNotes e4 f @@ -193,17 +212,34 @@ b c @end lilypond +Notation objects which are attached to invisible notes are still +visible. + +@lilypond[verbatim,quote,relative=2] +c4( d) +\hideNotes +e4(\p f)-- +@end lilypond + + @predefined +@funindex \hideNotes +@funindex \unHideNotes @code{\hideNotes}, @code{\unHideNotes} @seealso -Snippets: @lsrdir{Editorial,Editorial-annotations}. +Snippets: +@rlsr{Editorial annotations}. + +Internals Reference: +@rinternals{Note_spacing_engraver}, +@rinternals{NoteSpacing}. @node Coloring objects -@subsubsection Coloring objects +@unnumberedsubsubsec Coloring objects @cindex colored objects @cindex colors @@ -212,10 +248,10 @@ Snippets: @lsrdir{Editorial,Editorial-annotations}. @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}. +Individual objects may be assigned colors. Valid color names +are listed in the @ref{List of colors}. -@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +@lilypond[verbatim,quote,relative=2] \override NoteHead #'color = #red c4 c \override NoteHead #'color = #(x11-color 'LimeGreen) @@ -236,69 +272,66 @@ 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] +@lilypond[verbatim,quote,relative=2] \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2) \set Staff.instrumentName = \markup { \with-color #(x11-color 'navy) "Clarinet" } -gis4 a + +gis8 a \override Beam #'color = #(x11-color "medium turquoise") 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. +Exact RGB colors can be specified using the Scheme function +@code{rgb-color}. -@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" - } - \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[verbatim,quote,relative=2] +\override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2) +\set Staff.instrumentName = \markup { + \with-color #(x11-color 'navy) "Clarinet" } + +\override Stem #'color = #(rgb-color 0 0 0) +gis8 a +\override Stem #'color = #(rgb-color 1 1 1) +gis8 a +\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}. +Snippets: +@rlsr{Editorial annotations}. @knownissues -An x11 color is not necessarily exactly the same shade as a +An X11 color is not necessarily exactly the same shade as a 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). +Not all X11 colors are distinguishable in a web browser, i.e., +a web browser might not display a difference between @code{'LimeGreen} +and @code{'ForestGreen}. For web use normal colors are recommended +(i.e., @code{#blue}, @code{#green}, @code{#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 @@ -306,42 +339,41 @@ 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 ->2-\parenthesize -. -d g -< - c, - \parenthesize fis -> -@end lilypond +the music event. When prefixed to a chord, it parenthesizes every +note. Individual notes inside a chord may also be parenthesized. -This only functions inside chords, to parenthesize a single note it -must be enclosed with @code{<>} as if it is a chord. +@lilypond[verbatim,quote,relative=2] +c2 \parenthesize d +c2 \parenthesize +c2 +@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[verbatim,quote,relative=2] +c2-\parenthesize -. d +c2 \parenthesize r @end lilypond @seealso -Snippets: @lsrdir{Editorial,Editorial-annotations}. +Snippets: +@rlsr{Editorial annotations}. + +Internals Reference: +@rinternals{Parenthesis_engraver}, +@rinternals{ParenthesesItem}, +@rinternals{parentheses-interface}. + +@knownissues + +Parenthesizing a chord prints parentheses around each individual +note, instead of a single large parenthesis around the entire +chord. @node Stems -@subsubsection Stems +@unnumberedsubsubsec Stems @cindex stem @@ -366,24 +398,27 @@ made invisible. @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,doctitle] +{default-direction-of-stems-on-the-center-line-of-the-staff.ly} @seealso +Notation Reference: +@ref{Direction and placement}. + +Snippets: +@rlsr{Editorial annotations}. -Snippets: @lsrdir{Editorial,Editorial-annotations}. +Internals Reference: +@rinternals{Stem_engraver}, +@rinternals{Stem}, +@rinternals{stem-interface}. @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:: @@ -392,89 +427,130 @@ 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] +@lilypond[verbatim,quote,relative=2] \new Voice \with { \consists "Balloon_engraver" } - { - \time 2/4 - \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" } - a'8 - 4. - } +{ + \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" } + 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 is used like \once \override to -attach text to any grob, and the latter is used like \tweak, -typically within chords, to attach text to an individual note. - @cindex balloon @cindex notation, explaining +There are two music functions, @code{balloonGrobText} and +@code{balloonText}; the former is used like +@w{@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. + +Balloon text normally influences note spacing, but this can be +altered: + +@lilypond[verbatim,quote,relative=2] +\new Voice \with { \consists "Balloon_engraver" } +{ + \balloonLengthOff + \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" } + a8 + \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" } + r + \balloonLengthOn + 2. +} +@end lilypond + + +@predefined + +@funindex balloonLengthOn +@funindex balloonLengthOff +@code{\balloonLengthOn}, @code{\balloonLengthOff} + @seealso -Snippets: @lsrdir{Editorial,Editorial-annotations}. +Snippets: +@rlsr{Editorial annotations}. -Internals Reference: @internalsref{text-balloon-interface}. +Internals Reference: +@rinternals{Balloon_engraver}, +@rinternals{BalloonTextItem}, +@rinternals{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] +The @code{Grid_point_engraver} must be used to create the end +points of the lines, while the @code{Grid_line_span_engraver} must +be used to actually draw the lines. By default this centers grid +lines horizontally below and to the left side of each note head. +Grid lines extend from the middle lines of each staff. The +@code{gridInterval} must specify the duration between the grid +lines. + +@lilypond[verbatim,quote] \layout { \context { \Staff - \consists "Grid_point_engraver" %% sets of grid + \consists "Grid_point_engraver" gridInterval = #(ly:make-moment 1 4) } + \context { + \Score + \consists "Grid_line_span_engraver" + } } -\new Score \with { - \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 +\score { + \new ChoirStaff << + \new Staff \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 { - c4 g' f e + \new Staff \relative c { + \clef bass + \stemDown + c4 g' f e } - } ->> + >> +} @end lilypond -@seealso +@snippets -Snippets: @lsrdir{Editorial,Editorial-annotations}. +@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle] +{grid-lines--changing-their-appearance.ly} +@seealso + +Snippets: +@rlsr{Editorial annotations}. + +Internals Reference: +@rinternals{Grid_line_span_engraver}, +@rinternals{Grid_point_engraver}, +@rinternals{GridLine}, +@rinternals{GridPoint}, +@rinternals{grid-line-interface}, +@rinternals{grid-point-interface}. @node Analysis brackets -@subsubsection Analysis brackets +@unnumberedsubsubsec Analysis brackets @cindex brackets @cindex phrasing brackets @@ -482,31 +558,46 @@ 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}. +pieces. Simple horizontal brackets are supported. -@lilypond[quote,ragged-right,verbatim] -\score { - \relative c'' { - c4\startGroup\startGroup - c4\stopGroup - c4\startGroup - c4\stopGroup\stopGroup +@lilypond[verbatim,quote] +\layout { + \context { + \Voice + \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[verbatim,quote] +\layout { + \context { + \Voice + \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: +@rlsr{Editorial annotations}. -Internals Reference: @internalsref{HorizontalBracket}, -@internalsref{Horizontal_bracket_engraver}, @internalsref{Staff}. +Internals Reference: +@rinternals{Horizontal_bracket_engraver}, +@rinternals{HorizontalBracket}, +@rinternals{horizontal-bracket-interface}, +@rinternals{Staff}.