X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Feditorial.itely;h=7bdca44e346334f8deb201a0d70574af57dc0282;hb=db1b4bee7d0792351e368e776f197b1bca7050cb;hp=c6d15041a60593e3af74e8fae17019431a02b739;hpb=1db42cdf3309b31c12b47addab01b8a40f2d2ff4;p=lilypond.git diff --git a/Documentation/user/editorial.itely b/Documentation/user/editorial.itely index c6d15041a6..7bdca44e34 100644 --- a/Documentation/user/editorial.itely +++ b/Documentation/user/editorial.itely @@ -6,7 +6,7 @@ version that you are working on. See TRANSLATION for details. @end ignore -@c \version "2.11.38" +@c \version "2.11.51" @node Editorial annotations @section Editorial annotations @@ -40,14 +40,34 @@ inside the staff. @node Selecting notation font size @unnumberedsubsubsec Selecting notation font size -@cindex font size -@cindex font size, selecting -@cindex selecting font size +@cindex font size (notation) scaling +@cindex font size (notation) +@cindex selecting font size (notation) +@cindex notation font size +@cindex note heads +@funindex fontSize +@funindex font-size +@funindex magstep +@funindex \huge +@funindex \large +@funindex \normalsize +@funindex \small +@funindex \tiny +@funindex \teeny +@funindex huge +@funindex large +@funindex normalsize +@funindex small +@funindex tiny +@funindex teeny 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] +@warning{For font sizes of text, see +@ref{Selecting font and font size}.} + +@lilypond[verbatim,quote,relative=2] \huge c4.-> d8---3 \large @@ -58,23 +78,21 @@ c4.-> d8---3 c4.-> d8---3 \tiny c4.-> d8---3 -\normalsize -c2 +\teeny +c4.-> d8---3 @end lilypond -@cindex font size scaling - -Internally, this sets the @code{fontSize} property. This in turns +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 two. The Scheme function +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. -@lilypond[quote,fragment,relative=2,verbatim,ragged-right] +@lilypond[verbatim,quote,relative=2] \set fontSize = #3 c4.-> d8---3 \override NoteHead #'font-size = #-4 @@ -85,12 +103,14 @@ c4.-> d8---3 c4.-> d8---3 @end lilypond -@cindex standard font size -@cindex font size, standard +@cindex standard font size (notation) +@cindex font size (notation), standard +@funindex font-interface +@funindex font-size 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 @@ -99,6 +119,8 @@ that use fonts. These are the ones supporting the @predefined +@funindex \teeny +@code{\teeny}, @funindex \tiny @code{\tiny}, @funindex \small @@ -113,10 +135,12 @@ that use fonts. These are the ones supporting the @seealso Snippets: -@lsrdir{Editorial,Editorial-annotations}. +@rlsr{Editorial annotations}. Internals Reference: -@internalsref{font-interface}. +@rinternals{fontSize}, +@rinternals{font-size}, +@rinternals{font-interface}. @node Fingering instructions @@ -124,77 +148,90 @@ Internals Reference: @cindex fingering @cindex finger change +@funindex \finger +@funindex finger 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 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 +@funindex \thumb +@funindex thumb -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 @cindex fingering chords +@cindex fingering instructions for chords @cindex chords, fingering 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{Controlling direction and placement}. +staff, see @ref{Direction and placement}. @snippets -@lilypondfile[verbatim,lilyquote,ragged-right,texidoc] +@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle] {controlling-the-placement-of-chord-fingerings.ly} +@lilypondfile[verbatim,lilyquote,texidoc,doctitle] +{allowing-fingerings-to-be-printed-inside-the-staff.ly} + @seealso Notation Reference: -@ref{Controlling direction and placement} +@ref{Direction and placement} Snippets: -@lsrdir{Editorial,Editorial-annotations}. +@rlsr{Editorial annotations}. Internals Reference: -@internalsref{FingeringEvent}, -@internalsref{fingering-event}, -@internalsref{Fingering_engraver}, -@internalsref{New_fingering_engraver}, -@internalsref{Fingering}. +@rinternals{FingeringEvent}, +@rinternals{fingering-event}, +@rinternals{Fingering_engraver}, +@rinternals{New_fingering_engraver}, +@rinternals{Fingering}. @node Hidden notes @unnumberedsubsubsec Hidden notes -@cindex Hidden notes -@cindex Invisible notes -@cindex Transparent notes +@cindex hidden notes +@cindex invisible notes +@cindex transparent notes +@cindex notes, hidden +@cindex notes, invisible +@cindex notes, transparent @funindex \hideNotes +@funindex hideNotes @funindex \unHideNotes +@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 @@ -206,6 +243,16 @@ 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 @code{\hideNotes}, @code{\unHideNotes} @@ -213,11 +260,11 @@ c @seealso Snippets: -@lsrdir{Editorial,Editorial-annotations}. +@rlsr{Editorial annotations}. Internals Reference: -@internalsref{Note_spacing_engraver}, -@internalsref{NoteSpacing}. +@rinternals{Note_spacing_engraver}, +@rinternals{NoteSpacing}. @node Coloring objects @@ -229,11 +276,18 @@ Internals Reference: @cindex colored notes @cindex coloring notes @cindex notes, colored +@cindex x11 color +@cindex x11-color +@cindex with-color +@funindex color +@funindex \with-color +@funindex with-color +@funindex x11-color -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) @@ -242,7 +296,6 @@ d e @end lilypond -@cindex x11-color The full range of colors defined for X11 can be accessed by using the Scheme function @code{x11-color}. The function takes one @@ -254,7 +307,7 @@ 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" @@ -272,21 +325,24 @@ gis a b2 cis @end lilypond -You can get exact RGB colors by specifying the rgb-color number. +@cindex rgb-color +@cindex color, rgb +@cindex rgb color +@funindex rgb-color -@lilypond[quote,ragged-right,verbatim,fragment,relative=2] +Exact RGB colors can be specified using the Scheme function +@code{rgb-color}. + +@lilypond[verbatim,quote,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 @@ -298,15 +354,22 @@ Notation Reference: the input}. Snippets: -@lsrdir{Editorial,Editorial-annotations}. +@rlsr{Editorial annotations}. + +@cindex x11 color +@cindex colored notes in chords +@cindex notes, colored in chords +@cindex color in chords +@funindex x11-color @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 @@ -320,19 +383,22 @@ Notes in a chord cannot be colored with @code{\override}; use @cindex notes, ghost @cindex notes, parenthesized @cindex parentheses +@funindex \parenthesize +@funindex parenthesize Objects may be parenthesized by prefixing @code{\parenthesize} to -the music event. When applied to a chord, it parenthesizes every -note. +the music event. When prefixed to a chord, it parenthesizes every +note. Individual notes inside a chord may also be parenthesized. -@lilypond[quote,relative=2,fragment,verbatim,ragged-right] +@lilypond[verbatim,quote,relative=2] c2 \parenthesize d c2 \parenthesize +c2 @end lilypond Non-note objects may be parenthesized as well. -@lilypond[quote,relative=2,fragment,verbatim,ragged-right] +@lilypond[verbatim,quote,relative=2] c2-\parenthesize -. d c2 \parenthesize r @end lilypond @@ -340,18 +406,26 @@ c2 \parenthesize r @seealso Snippets: -@lsrdir{Editorial,Editorial-annotations}. +@rlsr{Editorial annotations}. Internals Reference: -@internalsref{Parenthesis_engraver}, -@internalsref{ParenthesesItem}, -@internalsref{parentheses-interface}. +@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 @unnumberedsubsubsec Stems @cindex stem +@cindex stem, invisible +@cindex invisible stem Whenever a note is found, a @code{Stem} object is created automatically. For whole notes and rests, they are also created but @@ -374,20 +448,20 @@ made invisible. @cindex stem, down @cindex stem, neutral -@lilypondfile[verbatim,lilyquote,ragged-right,texidoc] +@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle] {default-direction-of-stems-on-the-center-line-of-the-staff.ly} @seealso Notation Reference: -@ref{Controlling direction and placement}. +@ref{Direction and placement}. Snippets: -@lsrdir{Editorial,Editorial-annotations}. +@rlsr{Editorial annotations}. Internals Reference: -@internalsref{Stem_engraver}, -@internalsref{Stem}, -@internalsref{stem-interface}. +@rinternals{Stem_engraver}, +@rinternals{Stem}, +@rinternals{stem-interface}. @node Outside the staff @@ -405,116 +479,169 @@ from outside of the staff. @node Balloon help @unnumberedsubsubsec Balloon help +@cindex balloon +@cindex notation, explaining +@cindex balloon help +@cindex help, balloon +@funindex \balloonGrobText +@funindex \balloonText +@funindex Balloon_engraver +@funindex balloonGrobText +@funindex balloonText + 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. -@lilypond[quote,verbatim,fragment,ragged-right,relative=2] +@lilypond[verbatim,quote,relative=2] \new Voice \with { \consists "Balloon_engraver" } { \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" } a8 - \balloonGrobText #'Rest #' (-4 . -4) \markup { "I'm a rest" } + \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 @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. +@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. -@cindex balloon -@cindex notation, explaining +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 +@funindex \balloonLengthOn +@funindex \balloonLengthOff + +@code{\balloonLengthOn}, @code{\balloonLengthOff} @seealso Snippets: -@lsrdir{Editorial,Editorial-annotations}. +@rlsr{Editorial annotations}. Internals Reference: -@internalsref{Balloon_engraver}, -@internalsref{BalloonTextItem}, -@internalsref{balloon-interface}. +@rinternals{Balloon_engraver}, +@rinternals{BalloonTextItem}, +@rinternals{balloon-interface}. @node Grid lines @unnumberedsubsubsec Grid lines +@cindex grid lines +@cindex lines, grid +@cindex vertical lines between staves +@cindex lines, vertical between staves +@funindex Grid_point_engraver +@funindex Grid_line_span_engraver +@funindex gridInterval + Vertical lines can be drawn between staves synchronized with the notes. -@lilypond[quote,verbatim,ragged-right] +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 - % 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" } + \context { + \Score + \consists "Grid_line_span_engraver" + } +} -\new ChoirStaff << - \new Staff { - \relative c'' { +\score { + \new ChoirStaff << + \new Staff \relative c'' { \stemUp c4. d8 e8 f g4 } - } - \new Staff { - \clef bass - \relative c { + \new Staff \relative c { + \clef bass \stemDown - c4 g' f e + c4 g' f e } - } ->> + >> +} @end lilypond @snippets -@lilypondfile[verbatim,lilyquote,ragged-right,texidoc] -{grid-lines-changing-their-appearance.ly} +@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle] +{grid-lines--changing-their-appearance.ly} @seealso Snippets: -@lsrdir{Editorial,Editorial-annotations}. +@rlsr{Editorial annotations}. Internals Reference: -@internalsref{Grid_line_span_engraver}, -@internalsref{Grid_point_engraver}, -@internalsref{GridLine}, -@internalsref{GridPoint}, -@internalsref{grid-line-interface}, -@internalsref{grid-point-interface}. +@rinternals{Grid_line_span_engraver}, +@rinternals{Grid_point_engraver}, +@rinternals{GridLine}, +@rinternals{GridPoint}, +@rinternals{grid-line-interface}, +@rinternals{grid-point-interface}. @node Analysis brackets @unnumberedsubsubsec Analysis brackets @cindex brackets -@cindex phrasing brackets +@cindex bracket, phrasing +@cindex phrasing bracket @cindex musicological analysis @cindex note grouping bracket +@cindex horizontal bracket +@cindex bracket, horizontal +@funindex Horizontal_bracket_engraver +@funindex \startGroup +@funindex startGroup +@funindex \stopGroup +@funindex stopGroup Brackets are used in musical analysis to indicate structure in musical -pieces. LilyPond supports a simple form of horizontal brackets. +pieces. Simple horizontal brackets are supported. -@lilypond[quote,verbatim,ragged-right] +@lilypond[verbatim,quote] \layout { \context { - \Staff \consists "Horizontal_bracket_engraver" + \Voice + \consists "Horizontal_bracket_engraver" } } \relative c'' { @@ -525,10 +652,11 @@ pieces. LilyPond supports a simple form of horizontal brackets. Analysis brackets may be nested. -@lilypond[quote,verbatim,ragged-right] +@lilypond[verbatim,quote] \layout { \context { - \Staff \consists "Horizontal_bracket_engraver" + \Voice + \consists "Horizontal_bracket_engraver" } } \relative c'' { @@ -542,11 +670,11 @@ Analysis brackets may be nested. @seealso Snippets: -@lsrdir{Editorial,Editorial-annotations}. +@rlsr{Editorial annotations}. Internals Reference: -@internalsref{Horizontal_bracket_engraver}, -@internalsref{HorizontalBracket}, -@internalsref{horizontal-bracket-interface}, -@internalsref{Staff}. +@rinternals{Horizontal_bracket_engraver}, +@rinternals{HorizontalBracket}, +@rinternals{horizontal-bracket-interface}, +@rinternals{Staff}.