Update blank sheet music example again.

[lilypond.git] / Documentation / user / advanced-notation.itely

diff --git a/Documentation/user/advanced-notation.itely b/Documentation/user/advanced-notation.itely
index 5b9f613f58134b9b1277691e11853d5aced9b828..30042de160cfef64d5687736533b5caca4519fc1 100644 (file)
--- a/Documentation/user/advanced-notation.itely
+++ b/Documentation/user/advanced-notation.itely
@@ -75,9 +75,9 @@ The @code{\markup} is described in more detail in
 
 @refcommands
 
 
 @refcommands
 

-@findex \fatText
+@funindex \fatText

 @code{\fatText},
 @code{\fatText},

-@findex \emptyText
+@funindex \emptyText

 @code{\emptyText}.
 
 
 @code{\emptyText}.
 
 


@@ -157,13 +157,14 @@ Examples: @inputfileref{input/@/regression,text@/-spanner@/.ly}.
 @cindex segno on bar line
 @cindex fermata on bar line
 @cindex bar lines, symbols on
 @cindex segno on bar line
 @cindex fermata on bar line
 @cindex bar lines, symbols on

-@findex \mark
+@funindex \mark

 
 The @code{\mark} command is primarily used for
 @ref{Rehearsal marks},
 but it can also be used to put signs like coda,
 segno, and fermata on a bar line.  Use @code{\markup} to
 
 The @code{\mark} command is primarily used for
 @ref{Rehearsal marks},
 but it can also be used to put signs like coda,
 segno, and fermata on a bar line.  Use @code{\markup} to

-access the appropriate symbol
+access the appropriate symbol (symbols are listed in
+@ref{The Feta font})

 
 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
 c1 \mark \markup { \musicglyph #"scripts.ufermata" }
 
 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
 c1 \mark \markup { \musicglyph #"scripts.ufermata" }


@@ -290,7 +291,7 @@ but it can also be used anywhere text is called in lilypond
       #'break-visibility = #begin-of-line-invisible
     \override Score.RehearsalMark #'self-alignment-X = #right
 
       #'break-visibility = #begin-of-line-invisible
     \override Score.RehearsalMark #'self-alignment-X = #right
 

-    \set Staff.instrument = \markup{ \column{ Alto solo } }
+    \set Staff.instrumentName = \markup{ \column{ Alto solo } }

     c2^\markup{ don't be \flat }
     \override TextSpanner #'edge-text = #(cons (markup #:italic "rit" ) "")
     b2\startTextSpan
     c2^\markup{ don't be \flat }
     \override TextSpanner #'edge-text = #(cons (markup #:italic "rit" ) "")
     b2\startTextSpan


@@ -302,9 +303,8 @@ but it can also be used anywhere text is called in lilypond
 }
 @end lilypond
 
 }
 @end lilypond
 

-Text can also be placed on its own, away from any @code{\score}
-block.  This is primarily used in a @code{\book} (see
-@ref{Multiple movements}).
+A @code{\markup} command can also be placed on its own, away from any
+@code{\score} block, see @ref{Multiple scores in a book}.

 
 @lilypond[quote,ragged-right,verbatim]
 \markup{ Here is some text. }
 
 @lilypond[quote,ragged-right,verbatim]
 \markup{ Here is some text. }


@@ -450,7 +450,7 @@ The following commands can all be used inside @code{\markup @{ @}}.
 
 @cindex font selection
 @cindex font magnification
 
 @cindex font selection
 @cindex font magnification

-@findex font-interface
+@funindex font-interface

 
 By setting the object properties described below, you can select a
 font from the preconfigured font families.  LilyPond has default
 
 By setting the object properties described below, you can select a
 font from the preconfigured font families.  LilyPond has default


@@ -504,6 +504,12 @@ then set the
 
 @noindent
 Any font can be used, as long as it is available to Pango/FontConfig.
 
 @noindent
 Any font can be used, as long as it is available to Pango/FontConfig.

+To get a full list of all available fonts, run the command
+@example
+lilypond -dshow-available-fonts blabla
+@end example
+(the last argument of the command can be anything, but has to be present).
+

 
 The size of the font may be set with the @code{font-size}
 property. The resulting size is taken relative to the
 
 The size of the font may be set with the @code{font-size}
 property. The resulting size is taken relative to the


@@ -613,7 +619,7 @@ individual parts.
 @cindex Rests, multi measure
 @cindex Rests, full measure
 @cindex whole rests for a full measure
 @cindex Rests, multi measure
 @cindex Rests, full measure
 @cindex whole rests for a full measure

-@findex R
+@funindex R

 
 Rests for one full measure (or many bars) are entered using `@code{R}'.  It
 is specifically meant for full bar rests and for entering parts: the rest
 
 Rests for one full measure (or many bars) are entered using `@code{R}'.  It
 is specifically meant for full bar rests and for entering parts: the rest


@@ -735,7 +741,7 @@ Metronome settings can be entered as follows
 
 In the MIDI output, they are interpreted as a tempo change.  In the
 layout output, a metronome marking is printed
 
 In the MIDI output, they are interpreted as a tempo change.  In the
 layout output, a metronome marking is printed

-@findex \tempo
+@funindex \tempo

 @lilypond[quote,ragged-right,verbatim,fragment]
 \tempo 8.=120 c''1
 @end lilypond
 @lilypond[quote,ragged-right,verbatim,fragment]
 \tempo 8.=120 c''1
 @end lilypond


@@ -785,7 +791,7 @@ further away from the staff.
 @subsection Rehearsal marks
 
 @cindex Rehearsal marks
 @subsection Rehearsal marks
 
 @cindex Rehearsal marks

-@findex \mark
+@funindex \mark

 
 To print a rehearsal mark, use the @code{\mark} command
 
 
 To print a rehearsal mark, use the @code{\mark} command
 


@@ -898,7 +904,7 @@ Examples: @inputfileref{input/@/regression,rehearsal@/-mark@/-letter@/.ly},
 
 @cindex Bar numbers
 @cindex measure numbers
 
 @cindex Bar numbers
 @cindex measure numbers

-@findex currentBarNumber
+@funindex currentBarNumber

 
 Bar numbers are printed by default at the start of the line.  The
 number itself is stored in the @code{currentBarNumber} property, which
 
 Bar numbers are printed by default at the start of the line.  The
 number itself is stored in the @code{currentBarNumber} property, which


@@ -968,14 +974,17 @@ used to position the number correctly.
 In an orchestral score, instrument names are printed at the left side
 of the staves.
 
 In an orchestral score, instrument names are printed at the left side
 of the staves.
 

-This can be achieved by setting @internalsref{Staff}.@code{instrument}
-and @internalsref{Staff}.@code{instr}.  This will print a string before
-the start of the staff.  For the first staff, @code{instrument} is
-used, for the following ones, @code{instr} is used.
+This can be achieved by setting @internalsref{Staff}.@code{instrumentName}
+and @internalsref{Staff}.@code{shortInstrumentName}, or
+@internalsref{PianoStaff}.@code{instrumentName} and
+@internalsref{PianoStaff}.@code{shortInstrumentName}.  This will
+print text before
+the start of the staff.  For the first staff, @code{instrumentName} is
+used, for the following ones, @code{shortInstrumentName} is used.

 
 @lilypond[quote,verbatim,ragged-right,relative=1,fragment]
 
 @lilypond[quote,verbatim,ragged-right,relative=1,fragment]

-\set Staff.instrument = "Ploink "
-\set Staff.instr = "Plk "
+\set Staff.instrumentName = "Ploink "
+\set Staff.shortInstrumentName = "Plk "

 c1
 \break
 c''
 c1
 \break
 c''


@@ -985,7 +994,7 @@ You can also use markup texts to construct more complicated instrument
 names, for example
 
 @lilypond[quote,fragment,verbatim,ragged-right]
 names, for example
 
 @lilypond[quote,fragment,verbatim,ragged-right]

-\set Staff.instrument = \markup {
+\set Staff.instrumentName = \markup {

   \column { "Clarinetti"
             \line { "in B" \smaller \flat } } }
 c''1
   \column { "Clarinetti"
             \line { "in B" \smaller \flat } } }
 c''1


@@ -996,13 +1005,13 @@ If you wish to center the instrument names, you must center all of them
 @lilypond[quote,verbatim,ragged-right]
 { <<
 \new Staff {
 @lilypond[quote,verbatim,ragged-right]
 { <<
 \new Staff {

-  \set Staff.instrument = \markup {
+  \set Staff.instrumentName = \markup {

     \center-align { "Clarinetti"
       \line { "in B" \smaller \flat } } }
   c''1
 }
 \new Staff {
     \center-align { "Clarinetti"
       \line { "in B" \smaller \flat } } }
   c''1
 }
 \new Staff {

-  \set Staff.instrument = \markup{ \center-align { Vibraphone }}
+  \set Staff.instrumentName = \markup{ \center-align { Vibraphone }}

   c''1
 }
 >>
   c''1
 }
 >>


@@ -1018,32 +1027,35 @@ To center instrument names while leaving extra space to the right,
 \new StaffGroup \relative
 <<
   \new Staff {
 \new StaffGroup \relative
 <<
   \new Staff {

-    \set Staff.instrument
-    = \markup { \hcenter-in #10 "blabla" }
+    \set Staff.instrumentName = \markup { \hcenter-in #10 "blabla" }

     c1 c1
   }
   \new Staff {
     c1 c1
   }
   \new Staff {

-    \set Staff.instrument
-    = \markup { \hcenter-in #10 "blo" }
+    \set Staff.instrumentName = \markup { \hcenter-in #10 "blo" }

     c1 c1
   }
 >>
 @end lilypond
 
     c1 c1
   }
 >>
 @end lilypond
 

+To add instrument names to other contexts (such as @code{GrandStaff},
+@code{ChoirStaff}, or @code{StaffGroup}), the engraver must
+be added to that context.

 
 

-@seealso
+@example
+\layout@{
+  \context @{\GrandStaff \consists "Instrument_name_engraver"@}
+@}
+@end example

 
 

-Program reference: @internalsref{InstrumentName}.
+@noindent
+More information about adding and removing engravers can
+be found in @ref{Modifying context plug-ins}.

 
 

-@refbugs

 
 

-When you put a name on a grand staff or piano staff, the width of the
-brace is not taken into account. The following property setting can be
-used to move the instrument names to the left, in such situations.
+@seealso
+
+Program reference: @internalsref{InstrumentName}.

 
 

-@example
-\override Score.InstrumentName #'padding = #2.0
-@end example

 
 
 @node Instrument transpositions
 
 
 @node Instrument transpositions


@@ -1122,9 +1134,9 @@ the staff.  They are created by invoking the function
 }
 @end lilypond
 
 }
 @end lilypond
 

-The @code{set-octavation} function also takes -1 (for 8va bassa) and 2
-(for 15ma) as arguments.  Internally the function sets the properties
-@code{ottavation} (e.g., to @code{"8va"}) and
+The @code{set-octavation} function also takes -1 (for 8va bassa), 2@tie{}(for 15ma),
+and -2 (for 15ma bassa) as arguments.  Internally the function sets the properties
+@code{ottavation} (e.g., to @code{"8va"} or @code{"8vb"}) and

 @code{centralCPosition}.  For overriding the text of the bracket, set
 @code{ottavation} after invoking @code{set-octavation}, i.e.,
 
 @code{centralCPosition}.  For overriding the text of the bracket, set
 @code{ottavation} after invoking @code{set-octavation}, i.e.,
 


@@ -1154,7 +1166,7 @@ during an octavation bracket.
 @node Different editions from one source
 @subsection Different editions from one source
 
 @node Different editions from one source
 @subsection Different editions from one source
 

-@findex \tag
+@funindex \tag

 @cindex tag
 
 The @code{\tag} command marks music expressions with a name.  These
 @cindex tag
 
 The @code{\tag} command marks music expressions with a name.  These


@@ -1386,7 +1398,7 @@ or @code{\RemoveEmptyRhythmicStaffContext}.
 
 Another application is making ossia sections, i.e., alternative
 melodies on a separate piece of staff, with help of a Frenched
 
 Another application is making ossia sections, i.e., alternative
 melodies on a separate piece of staff, with help of a Frenched

-staff.  See @inputfileref{input/@/test,ossia@/.ly} for an example.
+staff.  

 
 
 @node Quoting other voices
 
 
 @node Quoting other voices


@@ -1618,15 +1630,6 @@ that fits into traditional notation categories, such as
 microtones, nested tuplet beams, and unusual fermatas, please
 see those sections of the documentation.
 
 microtones, nested tuplet beams, and unusual fermatas, please
 see those sections of the documentation.
 

-
-@c I don't think we should discourage modern composers who might
-@c want to sponsor new features.  :)
-@c  In general, the use of new, innovative notation makes a piece
-@c harder to understand and perform and its use should therefore be
-@c avoided.  For this reason, support for contemporary notation in
-@c LilyPond is limited.
-
-

 @menu
 * Polymetric notation::         
 * Time administration::         
 @menu
 * Polymetric notation::         
 * Time administration::         


@@ -1635,6 +1638,7 @@ see those sections of the documentation.
 * Special noteheads::           
 * Feathered beams::             
 * Improvisation::               
 * Special noteheads::           
 * Feathered beams::             
 * Improvisation::               

+* Selecting notation font size::  

 @end menu
 
 
 @end menu
 
 


@@ -1844,7 +1848,7 @@ seven sixteenths notes.
 @subsection Proportional notation
 @cindex Proportional notation
 
 @subsection Proportional notation
 @cindex Proportional notation
 

-Notes can be spaced proportional to their time-difference by
+Notes can be spaced proportionally to their time-difference by

 assigning a duration to @code{proportionalNotationDuration}
 
 @lilypond[quote,ragged-right,verbatim,relative=2,fragment]
 assigning a duration to @code{proportionalNotationDuration}
 
 @lilypond[quote,ragged-right,verbatim,relative=2,fragment]


@@ -1855,6 +1859,36 @@ assigning a duration to @code{proportionalNotationDuration}
 >>
 @end lilypond
 
 >>
 @end lilypond
 

+Setting this property only affects the ideal spacing between
+consecutive notes.  For true proportional notation, the following
+settings are also required.
+
+@itemize @bullet
+
+@item True proportional notation requires that symbols are allowed to
+overstrike each other.  That is achieved by removing the
+@internalsref{Separating_line_group_engraver} from
+@internalsref{Staff} context.
+
+@item Spacing influence of  prefatory matter (clefs, bar lines, etc.)
+is removed by setting the @code{strict-note-spacing} property to
+@code{#t} in @internalsref{SpacingSpanner} grob.
+
+@item Optical spacing tweaks are switched by setting 
+@code{uniform-stretching} in @internalsref{SpacingSpanner} to true.
+
+
+@end itemize
+
+@seealso
+
+@inputfileref{input/@/regression,spacing-proportional/.ly}
+@inputfileref{input/@/regression,spacing-strict-notespacing/.ly}
+@inputfileref{input/@/regression,spacing-strict-spacing-grace/.ly}
+
+An example of strict proportional notation is in the
+example file @file{input/proportional.ly}.
+

 
 @node Clusters
 @subsection Clusters
 
 @node Clusters
 @subsection Clusters


@@ -1925,26 +1959,22 @@ Program reference: @internalsref{NoteHead}.
 @node Feathered beams
 @subsection Feathered beams
 
 @node Feathered beams
 @subsection Feathered beams
 

-Feathered beams are not supported natively, but they can be faked by
-forcing two beams to overlap.  Here is an example,
+Feathered beams are printed by setting the @code{grow-direction}
+property of a @code{Beam}.  The @code{\featherDurations} function
+can be used to adjust note durations.

 
 

-@c don't change relative setting witout changing positions!

 @lilypond[ragged-right,relative=1,fragment,verbatim,quote]
 @lilypond[ragged-right,relative=1,fragment,verbatim,quote]

-\new Staff <<
-  \new Voice
-  {
-    \stemUp
-    \once \override Voice.Beam #'positions = #'(0 . 0.5)
-    c8[ c c c c ]
-  }
-  \new Voice {
-    \stemUp
-    \once \override Voice.Beam #'positions = #'(0 . -0.5)
-    c[ c c c c]
-  }
->>
+\featherDurations #(ly:make-moment 5 4) 
+{
+  \override Beam #'grow-direction = #LEFT
+  c16[ c c c c c c]
+}

 @end lilypond
 
 @end lilypond
 

+@refbugs
+
+The @code{\featherDuration} command only works with very short
+music snippets.

 
 @node Improvisation
 @subsection Improvisation
 
 @node Improvisation
 @subsection Improvisation


@@ -1978,6 +2008,62 @@ the following example
 @end lilypond
 
 
 @end lilypond
 
 

+@node Selecting notation font size
+@subsection 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.
+
+@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 Educational use
 @section Educational use
 
 @node Educational use
 @section Educational use
 


@@ -2004,17 +2090,18 @@ 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]
 The following example demonstrates its use.
 
 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]

-\applyOutput #'Voice
-  #(add-balloon-text 'NoteHead "heads, or tails?"
-      '(1 . -3))
-  c8
+\new Voice \with { \consists "Balloon_engraver" }
+{
+  \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
+  <c-\balloonText #'(-2 . -2) \markup { Hello }  >8
+}

 @end lilypond
 
 @noindent
 @end lilypond
 
 @noindent

-The function @code{add-balloon-text} takes the name of a grob, the
-label to print, and the position where to put the label relative to
-the object.  In the above example, the text ``heads or tails?'' ends
-3 spaces below and 1 space to the right of the marked head.
+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
 
 @cindex balloon
 @cindex notation, explaining


@@ -2039,6 +2126,7 @@ removing @code{Bar_number_engraver}.
 
 
 @lilypond[quote,verbatim]
 
 
 @lilypond[quote,verbatim]

+\layout{ indent = #0 }

 emptymusic = {
   \repeat unfold 2 % Change this for more lines.
   { s1\break }
 emptymusic = {
   \repeat unfold 2 % Change this for more lines.
   { s1\break }


@@ -2046,9 +2134,13 @@ emptymusic = {
 }
 \new Score \with {
   \override TimeSignature #'transparent = ##t
 }
 \new Score \with {
   \override TimeSignature #'transparent = ##t

+% un-comment this line if desired
+%  \override Clef #'transparent = ##t

   defaultBarType = #""
   \remove Bar_number_engraver
 } <<
   defaultBarType = #""
   \remove Bar_number_engraver
 } <<

+
+% modify these to get the staves you want

   \new Staff \emptymusic
   \new TabStaff \emptymusic
 >>
   \new Staff \emptymusic
   \new TabStaff \emptymusic
 >>


@@ -2062,8 +2154,8 @@ emptymusic = {
 @cindex Invisible notes
 @cindex Transparent notes
 
 @cindex Invisible notes
 @cindex Transparent notes
 

-@findex \hideNotes
-@findex \unHideNotes
+@funindex \hideNotes
+@funindex \unHideNotes

 Hidden (or invisible or transparent) notes can be useful in preparing theory
 or composition exercises.
 
 Hidden (or invisible or transparent) notes can be useful in preparing theory
 or composition exercises.
 


@@ -2098,10 +2190,10 @@ Shape note heads can be produced by setting @code{\aikenHeads} or
 Shapes are determined on the step in the scale, where the base of the
 scale is determined by  the @code{\key} command
 
 Shapes are determined on the step in the scale, where the base of the
 scale is determined by  the @code{\key} command
 

-@findex \key
-@findex shapeNoteStyles
-@findex \aikenHeads
-@findex \sacredHarpHeads
+@funindex \key
+@funindex shapeNoteStyles
+@funindex \aikenHeads
+@funindex \sacredHarpHeads

 
 Shape note heads are implemented through the @code{shapeNoteStyles}
 property.  Its value is a vector of symbols.  The k-th element indicates
 
 Shape note heads are implemented through the @code{shapeNoteStyles}
 property.  Its value is a vector of symbols.  The k-th element indicates


@@ -2133,11 +2225,11 @@ used in music for beginners
 The command @code{\setEasyHeads} overrides settings for the
 @internalsref{NoteHead} object.  To make the letters readable, it has
 to be printed in a large font size.  To print with a larger font, see
 The command @code{\setEasyHeads} overrides settings for the
 @internalsref{NoteHead} object.  To make the letters readable, it has
 to be printed in a large font size.  To print with a larger font, see

-@ref{Setting global staff size}.
+@ref{Setting the staff size}.

 
 @refcommands
 
 
 @refcommands
 

-@findex \setEasyHeads
+@funindex \setEasyHeads

 @code{\setEasyHeads}
 
 
 @code{\setEasyHeads}
 
 


@@ -2191,7 +2283,7 @@ e
 @end lilypond
 
 The full range of colors defined for X11 can be accessed by using the
 @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
+Scheme function x11-color.  The function takes one argument that can be a

 symbol
 
 @example
 symbol
 
 @example


@@ -2223,7 +2315,7 @@ deliberate nonsense.
 @lilypond[quote,ragged-right,verbatim]
 {
   \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
 @lilypond[quote,ragged-right,verbatim]
 {
   \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)

-  \set Staff.instrument = \markup {
+  \set Staff.instrumentName = \markup {

     \with-color #(x11-color 'navy) "Clarinet"
   }
   \time 2/4
     \with-color #(x11-color 'navy) "Clarinet"
   }
   \time 2/4