X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fadvanced-notation.itely;h=a414fe7b44c3909cb42013f05212ea98d2de7229;hb=a68f14eddcd0b57dde6be76abb41d3434f4761fb;hp=62116e26081fa387d2225b599ed7854292da008c;hpb=7176b36e20fa20671fb350a338860873e8f7268f;p=lilypond.git

diff --git a/Documentation/user/advanced-notation.itely b/Documentation/user/advanced-notation.itely
index 62116e2608..a414fe7b44 100644
--- 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
 
-@findex \fatText
+@funindex \fatText
 @code{\fatText},
-@findex \emptyText
+@funindex \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
-@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
-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" }
@@ -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
 
-    \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
@@ -302,9 +303,8 @@ but it can also be used anywhere text is called in 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. }
@@ -450,7 +450,7 @@ The following commands can all be used inside @code{\markup @{ @}}.
 
 @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
@@ -504,6 +504,12 @@ then set the
 
 @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
@@ -613,7 +619,7 @@ individual parts.
 @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
@@ -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
-@findex \tempo
+@funindex \tempo
 @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
-@findex \mark
+@funindex \mark
 
 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
-@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
@@ -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.
 
-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]
-\set Staff.instrument = "Ploink "
-\set Staff.instr = "Plk "
+\set Staff.instrumentName = "Ploink "
+\set Staff.shortInstrumentName = "Plk "
 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]
-\set Staff.instrument = \markup {
+\set Staff.instrumentName = \markup {
   \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 {
-  \set Staff.instrument = \markup {
+  \set Staff.instrumentName = \markup {
     \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
 }
 >>
@@ -1018,32 +1027,35 @@ To center instrument names while leaving extra space to the right,
 \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 {
-    \set Staff.instrument
-    = \markup { \hcenter-in #10 "blo" }
+    \set Staff.instrumentName = \markup { \hcenter-in #10 "blo" }
     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
@@ -1122,9 +1134,9 @@ the staff.  They are created by invoking the function
 }
 @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.,
 
@@ -1154,7 +1166,7 @@ during an octavation bracket.
 @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
@@ -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
-staff.  See @inputfileref{input/@/test,ossia@/.ly} for an example.
+staff.  
 
 
 @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.
 
-
-@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::         
@@ -1635,6 +1638,7 @@ see those sections of the documentation.
 * Special noteheads::           
 * Feathered beams::             
 * Improvisation::               
+* Selecting notation font size::  
 @end menu
 
 
@@ -1844,7 +1848,7 @@ seven sixteenths notes.
 @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]
@@ -1855,6 +1859,36 @@ assigning a duration to @code{proportionalNotationDuration}
 >>
 @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
@@ -1896,6 +1930,8 @@ accurately.  Use @code{<g a>8 <e a>8} instead.
 @node Special noteheads
 @subsection Special noteheads
 
+@cindex note heads, special
+
 Different noteheads are used by various instruments for various
 meanings -- crosses are used for ``parlato'' with vocalists, stopped
 notes on guitar; diamonds are used for harmonics on string instruments,
@@ -1923,26 +1959,22 @@ Program reference: @internalsref{NoteHead}.
 @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]
-\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
 
+@refbugs
+
+The @code{\featherDuration} command only works with very short
+music snippets.
 
 @node Improvisation
 @subsection Improvisation
@@ -1976,6 +2008,62 @@ the following example
 @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
 
@@ -2002,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]
-\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
-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
@@ -2060,8 +2149,8 @@ emptymusic = {
 @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.
 
@@ -2077,6 +2166,8 @@ g4 a
 @node Shape note heads
 @subsection Shape note heads
 
+@cindex note heads, shape
+
 In shape note head notation, the shape of the note head corresponds
 to the harmonic function of a note in the scale.  This notation was
 popular in the 19th century American song books.
@@ -2094,10 +2185,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
 
-@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
@@ -2113,6 +2204,8 @@ combinations are possible, e.g.
 @node Easy Notation note heads
 @subsection Easy Notation note heads
 
+@cindex note heads, practice
+@cindex note heads, easy notation
 @cindex easy notation
 @cindex Hal Leonard
 
@@ -2127,11 +2220,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
-@ref{Setting global staff size}.
+@ref{Setting the staff size}.
 
 @refcommands
 
-@findex \setEasyHeads
+@funindex \setEasyHeads
 @code{\setEasyHeads}
 
 
@@ -2185,7 +2278,7 @@ 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
+Scheme function x11-color.  The function takes one argument that can be a
 symbol
 
 @example
@@ -2217,7 +2310,7 @@ deliberate nonsense.
 @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