From: Graham Percival Date: Mon, 28 Jan 2008 19:57:22 +0000 (-0800) Subject: Rename file educational -> editorial. (we changed the doc section X-Git-Tag: release/2.11.38-1~10 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=28dd180e6a0306eee5c5f564da302e1dd4033a46;p=lilypond.git Rename file educational -> editorial. (we changed the doc section title 6 months ago) --- diff --git a/Documentation/user/editorial.itely b/Documentation/user/editorial.itely new file mode 100644 index 0000000000..ad18dd0818 --- /dev/null +++ b/Documentation/user/editorial.itely @@ -0,0 +1,473 @@ +@c -*- coding: utf-8; mode: texinfo; -*- +@ignore + Translation of GIT committish: FILL-IN-HEAD-COMMITTISH + + When revising a translation, copy the HEAD committish of the + version that you are working on. See TRANSLATION for details. +@end ignore + +@node Editorial annotations +@section Editorial annotations + +@lilypondfile[ragged-right,line-width=16\cm,staffsize=16,quote] +{editorial-headword.ly} + +@menu +* Inside the staff:: +* Outside the staff:: +@end menu + + +@node Inside the staff +@subsection Inside the staff + + +@menu +* Selecting notation font size:: +* Fingering instructions:: +* Hidden notes:: +* Coloring objects:: +* Parentheses:: +* Stems:: +@end menu + +@node Selecting notation font size +@unnumberedsubsubsec Selecting notation 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 +@end lilypond + +@noindent +It does not change the size of variable symbols, such as beams or +slurs. + +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 +\override NoteHead #'font-size = #-4 +c f +\override NoteHead #'font-size = #3 +g +@end lilypond + +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. +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 +@internalsref{font-interface} layout interface. + +@refcommands + +The following commands set @code{fontSize} for the current voice: + +@funindex \tiny +@code{\tiny}, +@funindex \small +@code{\small}, +@funindex \normalsize +@code{\normalsize}. + + +@node Fingering instructions +@unnumberedsubsubsec Fingering instructions + +@cindex fingering +@cindex finger change + +Fingering instructions can be entered using + +@example +@var{note}-@var{digit} +@end example + +For finger changes, use markup texts + +@lilypond[quote,verbatim,ragged-right,fragment,relative=1] +c4-1 c-2 c-3 c-4 +c^\markup { \finger "2 - 3" } +@end lilypond + +You can use the thumb-script to indicate that a note should be +played with the thumb (e.g., in cello music) + +@lilypond[quote,verbatim,ragged-right,fragment,relative=2] +8 +@end lilypond + +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 >4 +@end lilypond + + +@commonprop + +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 + + +@seealso + +Internals Reference: @internalsref{Fingering}. + +Examples: @lsr{expressive,fingering-chords.ly} + + + +@node Hidden notes +@unnumberedsubsubsec Hidden 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] +c4 d4 +\hideNotes +e4 f4 +\unHideNotes +g4 a +@end lilypond + + +@node Coloring objects +@unnumberedsubsubsec Coloring objects + +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] +\override NoteHead #'color = #red +c4 c +\override NoteHead #'color = #(x11-color 'LimeGreen) +d +\override Stem #'color = #blue +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 + +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 "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'' +} +@end lilypond + + +TODO +you can get exact RGB colors by specifying + +% black +\override Stem #'color = #(rgb-color 0 0 0) +% white +\override Stem #'color = #(rgb-color 1 1 1) +% dark blue +\override Stem #'color = #(rgb-color 0 0 0.5) + + +@seealso + +Appendix: @ref{List of colors}. + + +@refbugs +Not all x11 colors are distinguishable in a web browser. For web +use normal colors are recommended. + +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. + + +@node Parentheses +@unnumberedsubsubsec Parentheses + +@cindex ghost notes +@cindex notes, ghost +@cindex notes, parenthesized + +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 -. +@end lilypond + +This only functions inside chords, to parenthesize a single note it +must be enclosed with @code{<>} as if it is a chord. + +@example +< \parenthesize NOTE> +@end example + + +@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. + +@refcommands + +@funindex \stemUp +@code{\stemUp}, +@funindex \stemDown +@code{\stemDown}, +@funindex \stemNeutral +@code{\stemNeutral}. + + +@commonprop + +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 + + +@node Outside the staff +@subsection Outside the staff + + +@menu +* Balloon help:: +* Grid lines:: +* Blank music sheet:: +* Analysis brackets:: +@end menu + +@node 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 +} +@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. + +@cindex balloon +@cindex notation, explaining + +@seealso + +Internals Reference: @internalsref{text-balloon-interface}. + + +@node Grid lines +@unnumberedsubsubsec Grid lines + +Vertical lines can be drawn between staves synchronized with the +notes. + +@lilypond[ragged-right,quote,verbatim] +\layout { + \context { + \Staff + \consists "Grid_point_engraver" %% sets of grid + gridInterval = #(ly:make-moment 1 4) + } +} + +\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 + } + } + \new Staff { + %% centers grid lines vertically + \override Score.GridLine #'extra-offset = #'( 0.0 . 1.0 ) + \stemDown + \clef bass + \relative c { + c4 g' f e + } + } +>> +@end lilypond + +Examples: @lsrdir{education} + + +@node Blank music sheet +@unnumberedsubsubsec Blank music sheet + +@cindex Sheet music, empty +@cindex Staves, blank sheet + +A blank music sheet can be produced also by using invisible notes, +and removing @code{Bar_number_engraver}. + + +@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 +@unnumberedsubsubsec Analysis brackets + +@cindex brackets +@cindex phrasing brackets +@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 + } + \layout { + \context { + \Staff \consists "Horizontal_bracket_engraver" +}}} +@end lilypond + +@seealso + +Internals Reference: @internalsref{HorizontalBracket}. + + diff --git a/Documentation/user/educational.itely b/Documentation/user/educational.itely deleted file mode 100644 index ad18dd0818..0000000000 --- a/Documentation/user/educational.itely +++ /dev/null @@ -1,473 +0,0 @@ -@c -*- coding: utf-8; mode: texinfo; -*- -@ignore - Translation of GIT committish: FILL-IN-HEAD-COMMITTISH - - When revising a translation, copy the HEAD committish of the - version that you are working on. See TRANSLATION for details. -@end ignore - -@node Editorial annotations -@section Editorial annotations - -@lilypondfile[ragged-right,line-width=16\cm,staffsize=16,quote] -{editorial-headword.ly} - -@menu -* Inside the staff:: -* Outside the staff:: -@end menu - - -@node Inside the staff -@subsection Inside the staff - - -@menu -* Selecting notation font size:: -* Fingering instructions:: -* Hidden notes:: -* Coloring objects:: -* Parentheses:: -* Stems:: -@end menu - -@node Selecting notation font size -@unnumberedsubsubsec Selecting notation 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 -@end lilypond - -@noindent -It does not change the size of variable symbols, such as beams or -slurs. - -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 -\override NoteHead #'font-size = #-4 -c f -\override NoteHead #'font-size = #3 -g -@end lilypond - -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. -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 -@internalsref{font-interface} layout interface. - -@refcommands - -The following commands set @code{fontSize} for the current voice: - -@funindex \tiny -@code{\tiny}, -@funindex \small -@code{\small}, -@funindex \normalsize -@code{\normalsize}. - - -@node Fingering instructions -@unnumberedsubsubsec Fingering instructions - -@cindex fingering -@cindex finger change - -Fingering instructions can be entered using - -@example -@var{note}-@var{digit} -@end example - -For finger changes, use markup texts - -@lilypond[quote,verbatim,ragged-right,fragment,relative=1] -c4-1 c-2 c-3 c-4 -c^\markup { \finger "2 - 3" } -@end lilypond - -You can use the thumb-script to indicate that a note should be -played with the thumb (e.g., in cello music) - -@lilypond[quote,verbatim,ragged-right,fragment,relative=2] -8 -@end lilypond - -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 >4 -@end lilypond - - -@commonprop - -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 - - -@seealso - -Internals Reference: @internalsref{Fingering}. - -Examples: @lsr{expressive,fingering-chords.ly} - - - -@node Hidden notes -@unnumberedsubsubsec Hidden 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] -c4 d4 -\hideNotes -e4 f4 -\unHideNotes -g4 a -@end lilypond - - -@node Coloring objects -@unnumberedsubsubsec Coloring objects - -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] -\override NoteHead #'color = #red -c4 c -\override NoteHead #'color = #(x11-color 'LimeGreen) -d -\override Stem #'color = #blue -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 - -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 "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'' -} -@end lilypond - - -TODO -you can get exact RGB colors by specifying - -% black -\override Stem #'color = #(rgb-color 0 0 0) -% white -\override Stem #'color = #(rgb-color 1 1 1) -% dark blue -\override Stem #'color = #(rgb-color 0 0 0.5) - - -@seealso - -Appendix: @ref{List of colors}. - - -@refbugs -Not all x11 colors are distinguishable in a web browser. For web -use normal colors are recommended. - -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. - - -@node Parentheses -@unnumberedsubsubsec Parentheses - -@cindex ghost notes -@cindex notes, ghost -@cindex notes, parenthesized - -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 -. -@end lilypond - -This only functions inside chords, to parenthesize a single note it -must be enclosed with @code{<>} as if it is a chord. - -@example -< \parenthesize NOTE> -@end example - - -@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. - -@refcommands - -@funindex \stemUp -@code{\stemUp}, -@funindex \stemDown -@code{\stemDown}, -@funindex \stemNeutral -@code{\stemNeutral}. - - -@commonprop - -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 - - -@node Outside the staff -@subsection Outside the staff - - -@menu -* Balloon help:: -* Grid lines:: -* Blank music sheet:: -* Analysis brackets:: -@end menu - -@node 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 -} -@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. - -@cindex balloon -@cindex notation, explaining - -@seealso - -Internals Reference: @internalsref{text-balloon-interface}. - - -@node Grid lines -@unnumberedsubsubsec Grid lines - -Vertical lines can be drawn between staves synchronized with the -notes. - -@lilypond[ragged-right,quote,verbatim] -\layout { - \context { - \Staff - \consists "Grid_point_engraver" %% sets of grid - gridInterval = #(ly:make-moment 1 4) - } -} - -\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 - } - } - \new Staff { - %% centers grid lines vertically - \override Score.GridLine #'extra-offset = #'( 0.0 . 1.0 ) - \stemDown - \clef bass - \relative c { - c4 g' f e - } - } ->> -@end lilypond - -Examples: @lsrdir{education} - - -@node Blank music sheet -@unnumberedsubsubsec Blank music sheet - -@cindex Sheet music, empty -@cindex Staves, blank sheet - -A blank music sheet can be produced also by using invisible notes, -and removing @code{Bar_number_engraver}. - - -@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 -@unnumberedsubsubsec Analysis brackets - -@cindex brackets -@cindex phrasing brackets -@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 - } - \layout { - \context { - \Staff \consists "Horizontal_bracket_engraver" -}}} -@end lilypond - -@seealso - -Internals Reference: @internalsref{HorizontalBracket}. - - diff --git a/Documentation/user/notation.itely b/Documentation/user/notation.itely index 5e15d30923..722235e219 100644 --- a/Documentation/user/notation.itely +++ b/Documentation/user/notation.itely @@ -28,6 +28,6 @@ This chapter explains how to create musical notation. @include repeats.itely @include simultaneous.itely @include staff.itely -@include educational.itely +@include editorial.itely @include text.itely