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::
@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::
@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=1,verbatim]
-c8
-\set fontSize = #-4
-c f
-\set fontSize = #3
-g
+@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[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
+\teeny
+c4.-> d8---3
@end lilypond
-@noindent
-It does not change the size of variable symbols, such as beams or
-slurs.
-
-@cindex font size scaling
+@cindex font size (notation) 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 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.
-@lilypond[quote,fragment,relative=1,verbatim]
-c8
+@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
-@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.
+@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.
-
-@refcommands
+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 following commands set @code{fontSize} for the current voice:
+@predefined
+@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
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" }
@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]
-<a_\thumb a'-3>8 <b_\thumb b'-3>
+<a_\thumb a'-3>2 <b_\thumb b'-3>
@end lilypond
@cindex fingering chords
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 >
+<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)
-<c-1 e-3 a-5 > 4
-\set fingeringOrientations = #'(down)
-<c-1 e-3 a-5 >
-\set fingeringOrientations = #'(right)
-<c-1 e-3 a-5 >
-\set fingeringOrientations = #'(up)
-<c-1 e-3 a-5 >
-\set fingeringOrientations = #'(left down)
-<c-1 e-3 a-5 > 2
-\set fingeringOrientations = #'(up right down)
-<c-1 e-3 a-5 >
-@end lilypond
@seealso
-Snippets: @lsrdir{Editorial,Editorial-annotations}.
+Notation Reference:
+@ref{Controlling 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
-@cindex Hidden notes
-@cindex Invisible notes
-@cindex Transparent notes
+@node Hidden notes
+@unnumberedsubsubsec Hidden notes
+@cindex hidden notes
+@cindex invisible notes
+@cindex transparent notes
@funindex \hideNotes
@funindex \unHideNotes
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
+
+Notation objects which are attached to invisible notes are still
+visible.
+
+@lilypond[quote,ragged-right,verbatim,relative=2,fragment]
+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
@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=1]
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
\override NoteHead #'color = #red
c4 c
\override NoteHead #'color = #(x11-color 'LimeGreen)
@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
-
-@example
-\override Beam #'color = #(x11-color 'MediumTurquoise)
-@end example
-
-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
+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
+Exact RGB colors can be specified using the Scheme function
+@code{rgb-color}.
-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"
+}
+
\override Stem #'color = #(rgb-color 0 0 0)
-% white
+gis8 a
\override Stem #'color = #(rgb-color 1 1 1)
-% dark blue
+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}.
-@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.
+
+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}).
-An x11 color is not necessarily exactly the same shade as a
-similarly named normal color.
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
@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. 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]
+c2 \parenthesize d
+c2 \parenthesize <c e g>
+c2 <c \parenthesize e g>
@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.
-@example
-< \parenthesize NOTE>
-@end example
+@lilypond[quote,relative=2,fragment,verbatim,ragged-right]
+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
automatically. For whole notes and rests, they are also created but
made invisible.
-@refcommands
+@predefined
@funindex \stemUp
@code{\stemUp},
@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:
+@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::
* Grid lines::
-* Blank music sheet::
* Analysis brackets::
@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" }
- <f-\balloonText #'(-2 . -2) \markup { "I'm a note head" } >8
+ a8
+ \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
+ r
+ <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
}
@end lilypond
-@noindent
-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.
-
@cindex balloon
@cindex notation, explaining
+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.
+
+Balloon text normally influences note spacing, but this can be
+altered:
+
+@lilypond[quote,verbatim,fragment,ragged-right,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
+ <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>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[quote,verbatim,ragged-right]
\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: @lsrdir{Editorial,Editorial-annotations}.
-
-
-@node Blank music sheet
-@subsubsection Blank music sheet
-
-@cindex sheet music, empty
-@cindex staves, blank sheet
-@cindex blank staff paper
-@cindex staff paper, blank
+@snippets
-A blank music sheet can be produced also by using invisible notes,
-and removing @code{Bar_number_engraver}.
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+{grid-lines--changing-their-appearance.ly}
-@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
-
@seealso
-Snippets: @lsrdir{Editorial,Editorial-annotations}.
+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
@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[quote,verbatim,ragged-right]
+\layout {
+ \context {
+ \Voice
+ \consists "Horizontal_bracket_engraver"
}
- \layout {
- \context {
- \Staff \consists "Horizontal_bracket_engraver"
-}}}
+}
+\relative c'' {
+ c2\startGroup
+ d\stopGroup
+}
@end lilypond
-@seealso
+Analysis brackets may be nested.
+
+@lilypond[quote,verbatim,ragged-right]
+\layout {
+ \context {
+ \Voice
+ \consists "Horizontal_bracket_engraver"
+ }
+}
+\relative c'' {
+ c4\startGroup\startGroup
+ d4\stopGroup
+ e4\startGroup
+ d4\stopGroup\stopGroup
+}
+@end lilypond
-Snippets: @lsrdir{Editorial,Editorial-annotations}.
+@seealso
-Internals Reference: @internalsref{HorizontalBracket},
-@internalsref{Horizontal_bracket_engraver}, @internalsref{Staff}.
+Snippets:
+@rlsr{Editorial annotations}.
+Internals Reference:
+@rinternals{Horizontal_bracket_engraver},
+@rinternals{HorizontalBracket},
+@rinternals{horizontal-bracket-interface},
+@rinternals{Staff}.
projects / lilypond.git / blobdiff