]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/user/refman.itely
* lily/volta-engraver.cc (process_acknowledged_grobs):
[lilypond.git] / Documentation / user / refman.itely
index d75db2313bfb68b8863eb0742fb11f8d48afcc38..181de60db8d64cef20377c2bc1f4489f3d685522 100644 (file)
@@ -322,7 +322,7 @@ Durations can also be produced through GUILE extension mechanism.
 
 Dot placement for chords is not perfect.  In some cases, dots overlap:
 @lilypond[]
- \context Voice { <f,4. c'' d e f> }
+ <<f, c'' d e f>>4.
 @end lilypond
 
 
@@ -339,7 +339,7 @@ slurs, which indicate articulation, or phrasing slurs, which indicate
 musical phrasing.  A tie is entered using the tilde symbol `@code{~}'.
 
 @lilypond[fragment,verbatim,center]
-  e' ~ e' <c' e' g'> ~ <c' e' g'>
+  e' ~ e' <<c' e' g'>> ~ <<c' e' g'>>
 @end lilypond
 
 When a tie is applied to a chord, all note heads (whose pitches match) are
@@ -351,7 +351,7 @@ If you want less ties created for a chord, you can set
 for every tied chord.
 @lilypond[fragment,verbatim,center]
   \property Voice.sparseTies = ##t
-  <c' e' g'> ~ <c' e' g'>
+  <<c' e' g'>> ~ <<c' e' g'>>
 @end lilypond
 
 In its meaning a tie is just a way of extending a note duration, similar
@@ -599,9 +599,9 @@ preceding note.
 
 @lilypond[fragment,verbatim,center]
   \relative c' {
-    c <c e g
-    <c' e g>
-    <c, e' g>
+    c <<c e g>
+    <<c' e g>>
+    <<c, e' g>>
   }
 @end lilypond 
 @cindex @code{\notes}
@@ -752,23 +752,27 @@ emacsclient --no-wait +%l %f
 If you use xemacs instead of emacs, you use @code{(gnuserve-start)} in
 your @file{.emacs}, and set @code{XEDITOR} to @code{gnuclient -q +%l %f}
 
-For using Vim, set @code{XEDITOR} to @code{gvim --remote +%l %f}, or use this
-argument with xdvi's @code{-editor} option.
+For using Vim, set @code{XEDITOR} to @code{gvim --remote +%l %f}, or
+use this argument with xdvi's @code{-editor} option.
+
 @cindex NEdit
 For using NEdit, set @code{XEDITOR} to @code{nc -noask +%l %f}, or
 use this argument with xdvi's @code{-editor} option.
 
 If can also make your editor jump to the exact location of the note
-you clicked. This is only supported on Emacs. Users of version 20 must
-apply the patch @file{emacsclient.patch}. Users of version 21 must
-apply @file{server.el.patch} (version 21.2 and earlier).  At the top
-of the @code{ly} file, replace the @code{set!} line with the following
-line,
+you clicked. This is only supported on Emacs and VIM. Users of Emacs version
+20 must apply the patch @file{emacsclient.patch}. Users of version 21
+must apply @file{server.el.patch} (version 21.2 and earlier).  At the
+top of the @code{ly} file, replace the @code{set-point-and-click} line
+with the following line,
 @example
 #(ly:set-point-and-click 'line-column)
 @end example
 @cindex line-colomn-location
-and set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}.
+and set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}.  Vim
+users can set @var{XEDITOR} to @code{gvim --remote +:%l:norm%c| %f}.
+
+
 
 @refbugs
 
@@ -805,7 +809,7 @@ such as keys, clefs and time signatures.
 @cindex Staff notation
 
 @menu
-* Staff symbol::
+* Staff symbol::                
 * Key signature::               
 * Clef::                        
 * Time signature::              
@@ -962,6 +966,28 @@ inserted, and how automatic beams should be generated.  Changing the
 value of @code{timeSignatureFraction} also causes a time signature
 symbol to be printed.
 
+More options are available through the Scheme function
+@code{set-time-signature}. In combination with the
+@internalsref{Measure_grouping_engraver}, it will create
+@internalsref{MeasureGrouping} signs. Such signs ease reading
+rhythmically complex modern music.  In the following example, the 9/8
+measure is subdivided in 2, 2, 2 and 3. This is passed to
+@code{set-time-signature} as the third argument @code{(2 2 2 3)}.
+
+@lilypond[verbatim]
+\score { \notes \relative c'' {
+   #(set-time-signature 9 8 '(2 2 2 3))
+   g8 g d d g g a8-[-( bes g-]-) | 
+   #(set-time-signature 5 8 '(3 2))
+   a4. g4
+   }
+   \paper {
+       linewidth = -1.0
+       \translator { \StaffContext
+         \consists "Measure_grouping_engraver"
+   }}}
+@end lilypond 
+
 @c .   {Partial}
 @subsection Partial
 @cindex Partial
@@ -1609,7 +1635,7 @@ input file:
 
 @lilypond[singleline,fragment,verbatim]
 \property Staff.autoAccidentals = #'( Staff (any-octave . 0) )
-cis'4 <c'' c'> r2 | cis'4 <c' c''> r2 | <cis' c''> r | <c'' cis'> r | 
+cis'4 <<c'' c'>> r2 | cis'4 <<c' c''>> r2 | <<cis' c''>> r | <<c'' cis'>> r | 
 @end lilypond
 
 The only solution is to manually insert the problematic
@@ -1625,6 +1651,7 @@ accidentals using @code{!} and @code{?}.
 * Breath marks::                
 * Tempo::                       
 * Text spanners::               
+* Analysis brackets::           
 @end menu
 
 @node Slurs 
@@ -1788,6 +1815,32 @@ An application---or rather, a hack---is to fake octavation indications.
 @end lilypond
 
 
+@node Analysis brackets
+@subsection 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
+@internalsref{Staff} context.  A bracket is started with
+@code{\groupOpen} and closed with @code{\groupClose}. This produces
+@internalsref{HorizontalBracket} objects.
+
+@lilypond[singleline,verbatim]
+\score { \notes \relative c'' {  
+       c4-\groupOpen-\groupOpen
+       c4-\groupClose
+       c4-\groupOpen
+        c4-\groupClose-\groupClose
+  }
+  \paper { \translator {
+           \StaffContext \consists "Horizontal_bracket_engraver"
+       }}}
+@end lilypond
+
 @c .  {Ornaments}
 @node Ornaments
 @section Ornaments
@@ -2347,7 +2400,8 @@ command can be
 @item 'end-repeat
  Print a :| bar line
 @item (volta . @var{text})
- Print a volta bracket saying @var{text}.
+ Print a volta bracket saying @var{text} (the text can be specified
+ as a text string or as a markup text, see @ref{Text markup}).
 @item (volta . #f)
  Stop a running volta bracket
 @end table
@@ -2701,7 +2755,7 @@ dutch pitch names anymore. Hence you might wan't to reinclude
 up = \notes { crashcymbal4 hihat8 halfopenhihat hh hh hh openhihat }
 down = \notes { bassdrum4 snare8 bd r bd sn4 }
 \include "nederlands.ly"
-bass = \notes \transpose c, { a4. e8 r e g e }
+bass = \notes \transpose c c,, { a4. e8 r e g e }
 \score {
     <
         \apply #(drums->paper 'drums) \context Staff = drums <
@@ -2839,7 +2893,7 @@ Piano pedal instruction can be expressed using
 The symbols that are printed can be modified by setting
 @code{pedal@var{X}Strings}, where @var{X} is one of the pedal types:
 Sustain, Sostenuto or UnaCorda.  Refer to the generated documentation of
-@rgrob{SustainPedal}, for example, for more information.
+@internalsref{SustainPedal}, for example, for more information.
 
 Pedals can also be indicated by a sequence of brackets, by setting the 
 @code{pedal-type} property of SustainPedal objects: 
@@ -2890,11 +2944,11 @@ f'4 g'4 a'4 \sostenutoUp
 @cindex @code{\arpeggio}
 
 You can specify an arpeggio sign on a chord by attaching an
-@code{\arpeggio} to a note of the chord.
+@code{\arpeggio} to a chord.
 
 
 @lilypond[fragment,relative,verbatim]
-  \context Voice <c\arpeggio e g c>
+  <<c e g c>>-\arpeggio
 @end lilypond
 
 When an arpeggio crosses staves in piano music, you attach an arpeggio
@@ -2904,8 +2958,8 @@ to the chords in both staves, and set
 @lilypond[fragment,relative,verbatim]
   \context PianoStaff <
     \property PianoStaff.connectArpeggios = ##t
-    \context Voice = one  { <c'\arpeggio e g c> }
-    \context Voice = other { \clef bass  <c,,\arpeggio e g>}
+    \context Voice = one  { <<c' e g c>>-\arpeggio }
+    \context Voice = other { \clef bass  <<c,, e g>>-\arpeggio}
   >  
 @end lilypond
 
@@ -2919,9 +2973,9 @@ arpeggio, you should set the arpeggio object property
 @lilypond[fragment,relative,verbatim]
   \context Voice {
      \property Voice.Arpeggio \set #'arpeggio-direction = #1
-     <c\arpeggio e g c>
+     <<c e g c>>-\arpeggio
      \property Voice.Arpeggio \set #'arpeggio-direction = #-1
-     <c\arpeggio e g c>
+     <<c e g c>>-\arpeggio
   }
 @end lilypond
 
@@ -2936,8 +2990,8 @@ arpeggiate the chord. To draw these brackets, set the
     \property PianoStaff.connectArpeggios = ##t
     \property PianoStaff.Arpeggio \override
         #'molecule-callback = \arpeggioBracket
-    \context Voice = one  { <c'\arpeggio e g c> }
-    \context Voice = other { \clef bass  <c,,\arpeggio e g>}
+    \context Voice = one  { <<c' e g c>>-\arpeggio }
+    \context Voice = other { \clef bass  <<c,, e g>>-\arpeggio }
   >  
 @end lilypond
 
@@ -3069,7 +3123,6 @@ middle C, in string order: thus the notes are e, a, d & g)
     \notes {
       a,4 c' a e' e c' a e'
     }
-
   > 
 @end lilypond
 
@@ -3124,13 +3177,13 @@ the standard staff.
 
 LilyPond has support for both entering and printing chords. 
 @lilypond[verbatim,singleline]
-twoWays = \notes \transpose c'' {
+twoWays = \notes \transpose c c' {
   \chords {
     c1 f:sus4 bes/f
   }
-  <c e g>
-  <f bes c'>
-  <f bes d'>
+  <<c e g>>
+  <<f bes c'>>
+  <<f bes d'>>
   }
 
 \score {
@@ -3169,7 +3222,7 @@ Throughout these examples, chords have been shifted around the staff
 using @code{\transpose}.
 
 @lilypond[fragment,verbatim]
-\transpose c'' {
+\transpose c c' {
   \chords {
     c1  c:3-       c:7     c:8
     c:9 c:9-.5+.7+ c:3-.5- 
@@ -3191,7 +3244,7 @@ raises the 5th, `@code{dim}' which lowers the 5th,
 which replaces the 5th with a 4th.
 
 @lilypond[fragment,verbatim]
-\transpose c'' {
+\transpose c c' {
   \chords {
     c1:m c:min7 c:maj c:aug c:dim c:sus
   }
@@ -3204,7 +3257,7 @@ notes to be subtracted are listed after a @code{^} character,
 separated by dots.
 
 @lilypond[fragment,verbatim,center]
-  \transpose c'' {
+  \transpose c c' {
     \chords {
       c1^3 c:7^5.3 c:8^7
     }
@@ -3218,7 +3271,7 @@ transposed down until it is the lowest note in the chord.  If the note
 is not in the chord, a warning will be printed.
 
 @lilypond[fragment,verbatim,center]
-  \transpose c''' {
+  \transpose c c'' {
     \chords {
       c1 c/e c/g c:7/e
     }
@@ -3233,7 +3286,7 @@ adding the specified note to the chord, lowered by an octave,
 so it becomes the lowest note in the chord.
 
 @lilypond[fragment,verbatim,center]
-  \transpose c''' {
+  \transpose c c'' {
     \chords {
       c1 c/+c c/+g c:7/+b
     }
@@ -3276,12 +3329,12 @@ directly using simultaneous music.
 
 @lilypond[verbatim,singleline]
 scheme = \notes {
-  \chords {a1 b c} <d f g>  <e g b>
+  \chords {a1 b c} <<d f g>>  <<e g b>>
 }
 \score {
   \notes<
     \context ChordNames \scheme
-    \context Staff \transpose c'' \scheme
+    \context Staff \transpose c c' \scheme
   >
 }
 @end lilypond
@@ -3300,7 +3353,7 @@ scheme = \chords {
     \context ChordNames {
         \property ChordNames.chordChanges = ##t
         \scheme }
-    \context Staff \transpose c'' \scheme
+    \context Staff \transpose c c' \scheme
   >
 \paper{linewidth= 9.\cm}
 }
@@ -3313,9 +3366,9 @@ are entered as a list of pitches:
 
 @lilypond[verbatim,center,singleline]
 scheme = \notes {
-  <c'1 e' g'>
-  <e' g' c''>
-  <e e' g' c''>
+  <<c' e' g'>>1
+  <<e' g' c''>>
+  <<e e' g' c''>>
 }
 
 \score {
@@ -3357,7 +3410,7 @@ scheme = \chords {
     \context ChordNames = jazz {
       \property ChordNames.ChordName \override
         #'style = #'jazz \scheme }
-    \context Staff \transpose c'' \scheme
+    \context Staff \transpose c c' \scheme
   >
 }
 @end lilypond
@@ -3461,7 +3514,7 @@ adds a box around the bar numbers:
 @end example
 @lilypond[noindent,noquote]
 \score {
-    \context Staff \notes \transpose c''' {
+    \context Staff \notes \transpose c c'' {
        \property Score.BarNumber \override #'break-visibility = #end-of-line-invisible
        \property Score.barNumberVisibility = #(every-nth-bar-number-visible 5)
        \property Score.BarNumber \override #'molecule-callback =
@@ -3526,24 +3579,24 @@ the name to avoid a collision.
 A music expression can be transposed with @code{\transpose}.  The syntax
 is
 @example
-  \transpose @var{pitch} @var{musicexpr}
+  \transpose @var{from} @var{to} @var{musicexpr}
 @end example
 
-This means that middle C in @var{musicexpr} is transposed to
-@var{pitch}.
+This means that @var{musicexpr} is transposed to by the interval
+between @var{from} is @var{to}.
 
 @code{\transpose} distinguishes between enharmonic pitches: both
-@code{\transpose cis'} or @code{\transpose des'} will transpose up half
-a tone.  The first version will print sharps and the second version
-will print flats.
+@code{\transpose c cis} or @code{\transpose c des} will transpose up
+half a tone.  The first version will print sharps and the second
+version will print flats.
 
 @lilypond[singleline, verbatim]
 mus =\notes { \key d \major cis d fis g }
 \score { \notes \context Staff {
   \clef "F" \mus
   \clef "G"
-  \transpose g'' \mus
-  \transpose f'' \mus
+  \transpose c g' \mus
+  \transpose c f' \mus
 }}
 @end lilypond
 
@@ -3560,11 +3613,10 @@ effect music that appears inside a @code{\transpose}.
 
 Multi measure rests are entered using `@code{R}'. It is specifically
 meant for full bar rests and for entering parts: the rest can expand to
-fill a score with 
-rests, or it can be printed as a single multimeasure rest This expansion
-is controlled by the property @code{Score.skipBars}. If this is set to true,
-Lily will not expand empty measures, and the appropriate number is added
-automatically.
+fill a score with rests, or it can be printed as a single multimeasure
+rest This expansion is controlled by the property
+@code{Score.skipBars}. If this is set to true, Lily will not expand
+empty measures, and the appropriate number is added automatically.
 
 @lilypond[fragment,verbatim]
  \time 4/4 r1 | R1 | R1*2
@@ -3592,14 +3644,29 @@ rest centered in the measure, regardless of the time signature.
 
 @cindex whole rests for a full measure 
 
-The object for this object is @internalsref{MultiMeasureRest}.
+The object for this object is @internalsref{MultiMeasureRest}, and
+@internalsref{MultiMeasureRestNumber}.
 
 @refbugs
 
 Currently, there is no way to automatically condense multiple rests
 into a single multimeasure rest. Multi measure rests do not take part
-in rest collisions. There is no way to put texts centered on
-multi-measure rests.
+in rest collisions.
+
+Multi-measure rests do not accept @var{note}-@code{text} syntax for
+putting texts and scripts on the rest.  This has to be done by setting
+@code{#'text} in @internalsref{MultiMeasureRestNumber}. An identifier is
+provided for a fermata:
+
+@cindex text on multi-measure rest
+@cindex script on multi-measure rest
+@cindex fermata on multi-measure rest
+
+@lilypond[verbatim,fragment]
+  \time 3/4
+  \setMmRestFermata R2.
+@end lilypond
+
 
 @cindex condensing rests
 
@@ -3754,7 +3821,7 @@ output.
 
 @menu
 * Ancient note heads::          
-* Ancient clefs::               
+* Ancient clefs ::              
 * Custodes::                    
 * Ligatures::                   
 * Figured bass::                
@@ -4075,7 +4142,7 @@ a ligature by small square angles:
 
 @lilypond[singleline,verbatim]
 \score {
-    \notes \transpose c'' {
+    \notes \transpose c c' {
        \[ g c a f d' \]
        a g f
        \[ e f a g \]
@@ -4118,7 +4185,7 @@ Example:
 
 @lilypond[singleline,verbatim]
 \score {
-    \notes \transpose c'' {
+    \notes \transpose c c' {
        \property Score.timing = ##f
        \property Score.defaultBarType = "empty"
        \property Voice.NoteHead \set #'style = #'neo_mensural
@@ -4144,7 +4211,7 @@ following:
 
 @lilypond[singleline,verbatim]
 \score {
-    \notes \transpose c'' {
+    \notes \transpose c c' {
        \property Score.timing = ##f
        \property Score.defaultBarType = "empty"
        \property Voice.NoteHead \set #'style = #'neo_mensural
@@ -4240,8 +4307,8 @@ affecting a whole set of objects.  Second, you can select one specific
 object, and set a object property in that object.
 
 @menu
-* Tuning groups of objects ::     
-* Tuning per object ::            
+* Tuning groups of objects ::   
+* Tuning per object ::          
 * Font selection::              
 * Text markup::                 
 @end menu
@@ -4415,7 +4482,7 @@ property.
   \context Staff \outputproperty
   #(make-type-checker 'note-head-interface)
   #'extra-offset = #'(0.5 . 0.75)
-  <c8 e g> }
+  <<c e g>>8 }
 @end lilypond
 
 @cindex @code{extra-offset}
@@ -4846,9 +4913,9 @@ kneed stems.
 
 @lilypond
 \score {
-     \context PianoStaff \notes \transpose c''' <
+     \context PianoStaff \notes \transpose c c'' <
      \context Staff = up { s1 }
-     \context Staff = down { [c8 c \translator Staff=up <c d> c 
+     \context Staff = down { [c8 c \translator Staff=up <<c d>> c 
 \translator Staff=down c c c] }
      >
      \paper { linewidth = -1 }
@@ -4925,10 +4992,10 @@ This makes the following 28 measures (assuming 4/4 time) be broken every
 @cindex @code{indent}
 @cindex @code{linewidth}
 
-The most basic settings influencing the spacing are @code{linewidth}
-and @code{indent}, both set in the @code{\paper} block.  They control
-the indentation of the first line of music, and the lengths of the
-lines.  If @code{linewidth} set to a negative value, a single
+The most basic settings influencing the spacing are @code{indent} and
+@code{linewidth}. They are set in the @code{\paper} block. They
+control the indentation of the first line of music, and the lengths of
+the lines.  If @code{linewidth} set to a negative value, a single
 unjustified line is produced.  A similar effect for scores that are
 longer than one line, can be produced by setting @code{raggedright} to
 true in the @code{\paper} block.