Merge branch 'original' into HEAD

[lilypond.git] / Documentation / user / editorial.itely

diff --git a/Documentation/user/editorial.itely b/Documentation/user/editorial.itely
index 11afc1a0f749dc0d61dcff10332c22b02ed72560..674605cb26caa2b4804133e15c4501871f2d8735 100644 (file)
--- a/Documentation/user/editorial.itely
+++ b/Documentation/user/editorial.itely
@@ -32,7 +32,7 @@
 @end menu
 
 @node Selecting notation font size
 @end menu
 
 @node Selecting notation font size

-@unnumberedsubsubsec Selecting notation font size
+@subsubsection Selecting notation font size

 
 @cindex font size
 @cindex font size, selecting
 
 @cindex font size
 @cindex font size, selecting


@@ -41,12 +41,12 @@
 The easiest method of setting the font size of any context is by
 setting the @code{fontSize} property.
 
 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
 \set fontSize = #-4
 c f
 \set fontSize = #3

-g
+g8 a

 @end lilypond
 
 @noindent
 @end lilypond
 
 @noindent


@@ -65,12 +65,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.
 
 @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
 \override NoteHead #'font-size = #-4
 c f
 \override NoteHead #'font-size = #3

-g
+g8 a

 @end lilypond
 
 @cindex standard font size
 @end lilypond
 
 @cindex standard font size


@@ -85,7 +85,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.
 
 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:
 
 
 The following commands set @code{fontSize} for the current voice:
 


@@ -104,83 +104,77 @@ Internals Reference: @internalsref{font-interface}.
 
 
 @node Fingering instructions
 
 
 @node Fingering instructions

-@unnumberedsubsubsec Fingering instructions
+@subsubsection Fingering instructions

 
 @cindex fingering
 @cindex finger change
 
 Fingering instructions can be entered using
 
 @cindex fingering
 @cindex finger change
 
 Fingering instructions can be entered using

+@var{note}-@var{digit}:

 
 

-@example
-@var{note}-@var{digit}
-@end example
+@lilypond[quote,verbatim,ragged-right,fragment,relative=2]
+c4-1 d-2 f-4 e-3
+@end lilypond

 
 

-For finger changes, use markup texts
+Use markup texts for finger changes. 

 
 

-@lilypond[quote,verbatim,ragged-right,fragment,relative=1]
-c4-1 c-2 c-3 c-4
-c^\markup { \finger "2 - 3" }
+@lilypond[quote,verbatim,ragged-right,fragment,relative=2]
+c4-1 d-2 f-4 c^\markup { \finger "2 - 3" }

 @end lilypond
 
 @cindex thumb-script
 
 @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]
 
 @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
 @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]
 
 @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
 
 
 @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)
 \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)
 \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
 
 @end lilypond
 

-

 @seealso
 
 Snippets: @lsrdir{Editorial,Editorial-annotations}.
 
 Internals Reference: @internalsref{Fingering}.
 
 @seealso
 
 Snippets: @lsrdir{Editorial,Editorial-annotations}.
 
 Internals Reference: @internalsref{Fingering}.
 

-Examples: @c @lsr{expressive,fingering-chords.ly}
-
-

 
 @node Hidden notes
 
 @node Hidden notes

-@unnumberedsubsubsec Hidden notes
+@subsubsection Hidden notes

 
 @cindex Hidden notes
 @cindex Invisible notes
 @cindex Transparent notes
 
 @cindex Hidden notes
 @cindex Invisible notes
 @cindex Transparent notes

-

 @funindex \hideNotes
 @funindex \unHideNotes
 
 @funindex \hideNotes
 @funindex \unHideNotes
 


@@ -188,21 +182,40 @@ Hidden (or invisible or transparent) notes can be useful in
 preparing theory or composition exercises.
 
 @lilypond[quote,ragged-right,verbatim,relative=2,fragment]
 preparing theory or composition exercises.
 
 @lilypond[quote,ragged-right,verbatim,relative=2,fragment]

-c4 d4
+c4 d

 \hideNotes
 \hideNotes

-e4 f4
+e4 f

 \unHideNotes
 \unHideNotes

-g4 a
+g a
+\hideNotes 
+b
+\unHideNotes
+c

 @end lilypond
 
 @end lilypond
 

+@predefined
+
+@code{\hideNotes}, @code{\unHideNotes}
+
+@seealso
+
+Snippets: @lsrdir{Editorial,Editorial-annotations}.
+

 
 @node Coloring objects
 
 @node Coloring objects

-@unnumberedsubsubsec Coloring objects
+@subsubsection Coloring objects
+
+@cindex colored objects
+@cindex colors
+@cindex coloring objects
+@cindex colored notes
+@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.  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)
 \override NoteHead #'color = #red
 c4 c
 \override NoteHead #'color = #(x11-color 'LimeGreen)


@@ -211,76 +224,72 @@ d
 e
 @end lilypond
 
 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
+@cindex x11-color

 
 

-@example
+The full range of colors defined for X11 can be accessed by using
+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"
+}
+gis4 a

 \override Beam #'color = #(x11-color "medium turquoise")
 \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.
+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

 
 

-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.
+You can get exact RGB colors by specifying the rgb-color number.

 
 

-@lilypond[quote,ragged-right,verbatim]
+@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 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''
+  \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

 }
 @end lilypond
 
 }
 @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
 
 @seealso
 

-Appendix: @ref{List of colors}.
+Notation Reference: @ref{List of colors}, @ref{Objects connected to
+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
 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},
 
 Notes in a chord cannot be colored with @code{\override}; use
 @code{\tweak} instead.  See @ref{Objects connected to the input},


@@ -288,39 +297,45 @@ for details.
 
 
 @node Parentheses
 
 
 @node Parentheses

-@unnumberedsubsubsec Parentheses
+@subsubsection Parentheses

 
 @cindex ghost notes
 @cindex notes, ghost
 @cindex notes, parenthesized
 
 @cindex ghost notes
 @cindex notes, ghost
 @cindex notes, parenthesized

+@cindex parentheses

 
 Objects may be parenthesized by prefixing @code{\parenthesize} to
 
 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]
 
 @lilypond[relative=2,fragment,verbatim,ragged-right]

-<
-  c
-  \parenthesize d
-  g
->4-\parenthesize -.
+c2 < \parenthesize d>
+<\parenthesize e> d

 @end lilypond
 
 @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.
+
+@lilypond[relative=2,fragment,verbatim,ragged-right]
+< c \parenthesize d g >2-\parenthesize -. d
+g < c, \parenthesize fis >
+@end lilypond
+
+@seealso

 
 

-@example
-< \parenthesize NOTE>
-@end example
+Snippets: @lsrdir{Editorial,Editorial-annotations}.

 
 
 @node Stems
 
 
 @node Stems

-@unnumberedsubsubsec Stems
+@subsubsection Stems
+
+@cindex stem

 
 

-Whenever a note is found, a @internalsref{Stem} object is created
-automatically.  For whole notes and rests, they are also created
-but made invisible.
+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},
 
 @funindex \stemUp
 @code{\stemUp},


@@ -330,7 +345,12 @@ but made invisible.
 @code{\stemNeutral}.
 
 
 @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
 
 
 To change the direction of stems on the center line of the staff, use
 


@@ -342,6 +362,10 @@ a4 b c b
 a4 b c b
 @end lilypond
 
 a4 b c b
 @end lilypond
 

+@seealso
+
+Snippets: @lsrdir{Editorial,Editorial-annotations}.
+

 
 @node Outside the staff
 @subsection Outside the staff
 
 @node Outside the staff
 @subsection Outside the staff


@@ -350,12 +374,11 @@ a4 b c b
 @menu
 * Balloon help::                
 * Grid lines::                  
 @menu
 * Balloon help::                
 * Grid lines::                  

-* Blank music sheet::           

 * Analysis brackets::           
 @end menu
 
 @node Balloon help
 * 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
 
 Elements of notation can be marked and named with the help of a
 square balloon.  The primary purpose of this feature is to explain


@@ -365,28 +388,32 @@ The following example demonstrates its use.
 
 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
 \new Voice \with { \consists "Balloon_engraver" }
 
 @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" }
+       a'8
+       <c' g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } 
+c''>4. 
+     }

 @end lilypond
 
 @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
 
 
 @cindex balloon
 @cindex notation, explaining
 
 @seealso
 

+Snippets: @lsrdir{Editorial,Editorial-annotations}.
+

 Internals Reference: @internalsref{text-balloon-interface}.
 
 
 @node Grid lines
 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.
 
 Vertical lines can be drawn between staves synchronized with the
 notes.


@@ -395,15 +422,19 @@ notes.
 \layout {
   \context {
     \Staff
 \layout {
   \context {
     \Staff

-    \consists "Grid_point_engraver" %% sets of grid
+    \consists "Grid_point_engraver" 
+    % sets up grids

     gridInterval = #(ly:make-moment 1 4)
     gridInterval = #(ly:make-moment 1 4)

+    % this sets the grid interval to 1 quarternote (crotchet)

   }
 }
 
 \new Score \with {
   \consists "Grid_line_span_engraver"
   }
 }
 
 \new Score \with {
   \consists "Grid_line_span_engraver"

-  %% centers grid lines  horizontally below note heads
+  %% centers grid lines  horizontally below note heads by default 
+  %the grid lines are aligned with the left side of the notehead

   \override NoteColumn #'X-offset = #-0.5
   \override NoteColumn #'X-offset = #-0.5

+  % this moves them to the right half a staff space

 }
 
 \new ChoirStaff <<
 }
 
 \new ChoirStaff <<


@@ -414,8 +445,9 @@ notes.
     }
   }
   \new Staff {
     }
   }
   \new Staff {

-    %% centers grid lines  vertically

     \override Score.GridLine #'extra-offset = #'( 0.0 . 1.0 )
     \override Score.GridLine #'extra-offset = #'( 0.0 . 1.0 )

+    % by default the grid lines join the middle line of each staff,
+    % this moves them up one staff space

     \stemDown
     \clef bass
     \relative c {
     \stemDown
     \clef bass
     \relative c {


@@ -425,54 +457,25 @@ notes.
 >>
 @end lilypond
 
 >>
 @end lilypond
 

-Snippets: @lsrdir{Editorial,Editorial-annotations}.
-
+@seealso

 
 

-@node Blank music sheet
-@unnumberedsubsubsec Blank music sheet
+Snippets: @lsrdir{Editorial,Editorial-annotations}.

 
 

-@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
 
 
 @node Analysis brackets

-@unnumberedsubsubsec Analysis brackets
+@subsubsection Analysis brackets

 
 @cindex brackets
 @cindex phrasing brackets
 @cindex musicological analysis
 @cindex note grouping bracket
 
 
 @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]
 @code{\startGroup} and closed with @code{\stopGroup}.
 
 @lilypond[quote,ragged-right,verbatim]


@@ -486,11 +489,15 @@ horizontal brackets.  To use this, add the
   \layout {
     \context {
       \Staff \consists "Horizontal_bracket_engraver"
   \layout {
     \context {
       \Staff \consists "Horizontal_bracket_engraver"

-}}}
+    }
+  }
+}

 @end lilypond
 
 @seealso
 
 @end lilypond
 
 @seealso
 

-Internals Reference: @internalsref{HorizontalBracket}.
+Snippets: @lsrdir{Editorial,Editorial-annotations}.

 
 

+Internals Reference: @internalsref{HorizontalBracket},
+@internalsref{Horizontal_bracket_engraver}, @internalsref{Staff}.