]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/user/editorial.itely
Merge branch 'master' of ssh://kainhofer@git.sv.gnu.org/srv/git/lilypond into kainhofer
[lilypond.git] / Documentation / user / editorial.itely
index 340e8cdb93f8b9269c966eb2971bd0ca50cca02e..c13a4fbac0cf5d628ea3503830076aa4e489438c 100644 (file)
@@ -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,7 +36,7 @@
 @end menu
 
 @node Selecting notation font size
-@unnumberedsubsubsec Selecting notation font size
+@subsubsection Selecting notation font size
 
 @cindex font size
 @cindex font size, selecting
 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
+@lilypond[quote,fragment,relative=2,verbatim,ragged-right]
+c4
 \set fontSize = #-4
 c f
 \set fontSize = #3
-g
+g8 a
 @end lilypond
 
 @noindent
@@ -65,12 +69,12 @@ 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]
+c4
 \override NoteHead #'font-size = #-4
 c f
 \override NoteHead #'font-size = #3
-g
+g8 a
 @end lilypond
 
 @cindex standard font size
@@ -85,7 +89,7 @@ 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
+@predefined
 
 The following commands set @code{fontSize} for the current voice:
 
@@ -104,66 +108,67 @@ Internals Reference: @internalsref{font-interface}.
 
 
 @node Fingering instructions
-@unnumberedsubsubsec Fingering instructions
+@subsubsection Fingering instructions
 
 @cindex fingering
 @cindex finger change
 
 Fingering instructions can be entered using
+@var{note}-@var{digit}:
 
-@example
-@var{note}-@var{digit}
-@end example
+Fingering instructions may be manually placed above or below the
+staff, see @ref{Controlling direction and placement}.
 
-For finger changes, use markup texts
+@lilypond[quote,verbatim,ragged-right,fragment,relative=2]
+c4-1 d-2 f-4 e-3
+@end lilypond
 
-@lilypond[quote,verbatim,ragged-right,fragment,relative=1]
-c4-1 c-2 c-3 c-4
-c^\markup { \finger "2 - 3" }
+Use markup texts for finger changes. 
+
+@lilypond[quote,verbatim,ragged-right,fragment,relative=2]
+c4-1 d-2 f-4 c^\markup { \finger "2 - 3" }
 @end lilypond
 
 @cindex thumb-script
 
-
-You can use the thumb-script to indicate that a note should be
-played with the thumb (e.g., in cello music)
+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]
-<a_\thumb a'-3>8 <b_\thumb b'-3>
+<a_\thumb a'-3>2 <b_\thumb b'-3>
 @end lilypond
 
 @cindex fingering chords
 @cindex chords, fingering
 
 Fingerings for chords can also be added to individual notes of the
-chord by adding them after the pitches
+chord by adding them after the pitches.
 
 @lilypond[quote,verbatim,ragged-right,fragment,relative=2]
-< c-1 e-2 g-3 b-5 >4
+< c-1 e-2 g-3 b-5 >2 < d-1 f-2 a-3 c-5 >
 @end lilypond
 
 
-@commonprop
+@snippets
 
-You may exercise greater control over fingering chords by setting
-@code{fingeringOrientations}
+@code{fingeringOrientations} are used to control where the fingering
+numbers are placed.
 
-@lilypond[quote,verbatim,ragged-right,fragment,relative=1]
+@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 es-2 g-4 bes-5 > 4
+<c-1 e-3 a-5 > 2
 \set fingeringOrientations = #'(up right down)
-<c-1 es-2 g-4 bes-5 > 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)
-<es'-2>4
+<c-1 e-3 a-5 >
 @end lilypond
 
-
 @seealso
 
 Snippets: @lsrdir{Editorial,Editorial-annotations}.
@@ -172,12 +177,11 @@ Internals Reference: @internalsref{Fingering}.
 
 
 @node Hidden notes
-@unnumberedsubsubsec Hidden notes
+@subsubsection Hidden notes
 
 @cindex Hidden notes
 @cindex Invisible notes
 @cindex Transparent notes
-
 @funindex \hideNotes
 @funindex \unHideNotes
 
@@ -185,20 +189,28 @@ 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
+g a
+\hideNotes 
+b
 \unHideNotes
-g4 a
+c
 @end lilypond
 
+@predefined
+
+@code{\hideNotes}, @code{\unHideNotes}
+
 @seealso
 
 Snippets: @lsrdir{Editorial,Editorial-annotations}.
 
 
 @node Coloring objects
-@unnumberedsubsubsec Coloring objects
+@subsubsection Coloring objects
 
 @cindex colored objects
 @cindex colors
@@ -210,7 +222,7 @@ Snippets: @lsrdir{Editorial,Editorial-annotations}.
 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]
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 \override NoteHead #'color = #red
 c4 c
 \override NoteHead #'color = #(x11-color 'LimeGreen)
@@ -222,63 +234,55 @@ 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
-
-@example
-\override Beam #'color = #(x11-color 'MediumTurquoise)
-@end example
+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.
 
-or a string
+If @code{x11-color} cannot make sense of the parameter then the
+color returned defaults to black. 
 
-@example
-\override Beam #'color = #(x11-color "MediumTurquoise")
-@end example
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 
-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
+\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
+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
 
-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.
+You can get exact RGB colors by specifying the rgb-color number.
 
-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,fragment,relative=2]
 
-@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) 
+  
+  %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
 
@@ -287,20 +291,21 @@ the input}.
 
 Snippets: @lsrdir{Editorial,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.
+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
-@unnumberedsubsubsec Parentheses
+@subsubsection Parentheses
 
 @cindex ghost notes
 @cindex notes, ghost
@@ -308,22 +313,19 @@ for details.
 @cindex parentheses
 
 Objects may be parenthesized by prefixing @code{\parenthesize} to
-the music event,
+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.
 
 @lilypond[relative=2,fragment,verbatim,ragged-right]
-<
-  c
-  \parenthesize d
-  g
->4-\parenthesize -.
+c2 < \parenthesize d>
 @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[relative=2,fragment,verbatim,ragged-right]
+< c d g >2-\parenthesize -. d
+@end lilypond
 
 @seealso
 
@@ -331,7 +333,7 @@ Snippets: @lsrdir{Editorial,Editorial-annotations}.
 
 
 @node Stems
-@unnumberedsubsubsec Stems
+@subsubsection Stems
 
 @cindex stem
 
@@ -339,7 +341,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},
@@ -349,7 +351,7 @@ made invisible.
 @code{\stemNeutral}.
 
 
-@commonprop
+@snippets
 
 @cindex stem, direction
 @cindex stem, up
@@ -374,16 +376,17 @@ 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::                
 * Grid lines::                  
-* Blank music sheet::           
 * Analysis brackets::           
 @end menu
 
 @node Balloon help
-@unnumberedsubsubsec Balloon help
+@subsubsection 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
@@ -393,28 +396,33 @@ 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
-}
+     {
+      \time 2/4
+       \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
+       a8
+       <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } 
+c>4. 
+     }
+
 @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.
+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
 
 @seealso
 
+Snippets: @lsrdir{Editorial,Editorial-annotations}.
+
 Internals Reference: @internalsref{text-balloon-interface}.
 
 
 @node Grid lines
-@unnumberedsubsubsec Grid lines
+@subsubsection Grid lines
 
 Vertical lines can be drawn between staves synchronized with the
 notes.
@@ -423,15 +431,18 @@ notes.
 \layout {
   \context {
     \Staff
-    \consists "Grid_point_engraver" %% sets of grid
+    \consists "Grid_point_engraver" 
+    % sets up grids
     gridInterval = #(ly:make-moment 1 4)
+    % this sets the grid interval to 1 quarternote (crotchet)
   }
 }
 
 \new Score \with {
   \consists "Grid_line_span_engraver"
-  %% centers grid lines  horizontally below note heads
-  \override NoteColumn #'X-offset = #-0.5
+  %% 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
 }
 
 \new ChoirStaff <<
@@ -442,8 +453,6 @@ notes.
     }
   }
   \new Staff {
-    %% centers grid lines  vertically
-    \override Score.GridLine #'extra-offset = #'( 0.0 . 1.0 )
     \stemDown
     \clef bass
     \relative c {
@@ -453,54 +462,64 @@ notes.
 >>
 @end lilypond
 
-Snippets: @lsrdir{Editorial,Editorial-annotations}.
-
-
-@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}.
+To change the grid lines use \override.
 
 
-@lilypond[quote,verbatim]
-\layout{ indent = #0 }
-emptymusic = {
-  \repeat unfold 2 % Change this for more lines.
-  { s1\break }
-  \bar "|."
+@lilypond[ragged-right,quote,verbatim]
+\layout {
+  \context {
+    \Staff
+    \consists "Grid_point_engraver" 
+    % sets up grids
+       gridInterval = #(ly:make-moment 1 4)
+       % this sets the grid interval to 1 quarternote (crotchet)
+  }
 }
+
 \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
+  \consists "Grid_line_span_engraver"
+  \override NoteColumn #'X-offset = #-0.5
+  % this moves them to the right half a staff space
+}
+
+\new ChoirStaff <<
+  \new Staff {
+    \stemUp
+    \relative {
+      c'4. d8 e8 f g4
+    }
+  }
+  \new Staff {
+    \override Score.GridLine #'extra-offset = #'( 0.0 . 1.0 )
+    % this moves them up one staff space from the default position
+    \stemDown
+    \clef bass
+    \relative c {
+      c4  g'  f  e
+    }
+  }
 >>
 @end lilypond
 
+@seealso
+
+Snippets: @lsrdir{Editorial,Editorial-annotations}.
+
+
+
 
 @node Analysis brackets
-@unnumberedsubsubsec Analysis brackets
+@subsubsection 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
+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]
@@ -514,11 +533,15 @@ horizontal brackets.  To use this, add the
   \layout {
     \context {
       \Staff \consists "Horizontal_bracket_engraver"
-}}}
+    }
+  }
+}
 @end lilypond
 
 @seealso
 
-Internals Reference: @internalsref{HorizontalBracket}.
+Snippets: @lsrdir{Editorial,Editorial-annotations}.
 
+Internals Reference: @internalsref{HorizontalBracket},
+@internalsref{Horizontal_bracket_engraver}, @internalsref{Staff}.