nu wel 58

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

diff --git a/Documentation/user/refman.itely b/Documentation/user/refman.itely
index cd676041882f695a1b68332910811fb066fe232e..8833e029d86b407834bae9421878f157bc66f482 100644 (file)
--- a/Documentation/user/refman.itely
+++ b/Documentation/user/refman.itely
@@ -1,5 +1,4 @@
-
-@c Note:
+@c Note: -*-texinfo-*-

 @c
 @c A menu is needed before every deeper *section nesting of @node's; run
 @c     M-x texinfo-all-menus-update
 @c
 @c A menu is needed before every deeper *section nesting of @node's; run
 @c     M-x texinfo-all-menus-update


@@ -68,6 +67,7 @@ syntactical details are described at the end of the manual.
 * Chords::                      
 * Writing parts::               
 * Custodes::                    
 * Chords::                      
 * Writing parts::               
 * Custodes::                    

+* Figured bass::                

 * Tuning output::               
 * Page layout::                 
 * Output formats::              
 * Tuning output::               
 * Page layout::                 
 * Output formats::              


@@ -194,7 +194,7 @@ The verbose syntax for pitch specification is
   \pitch @var{scmpitch}
 @end example
 
   \pitch @var{scmpitch}
 @end example
 

-@var{scmpitch} is a pitch scheme object, see @ref{Pitch data type}.
+@var{scmpitch} is a pitch scheme object.

 
 In Note and Chord mode, pitches may be designated by names.  The default
 names are the Dutch note names.  The notes are specified by the letters
 
 In Note and Chord mode, pitches may be designated by names.  The default
 names are the Dutch note names.  The notes are specified by the letters


@@ -254,6 +254,14 @@ r1 r2 r4 r8
 The grob is @internalsref{Rest}. Whole bar rests centered in the bar are
 specified using @code{R}, see @ref{Multi measure rests}.
 
 The grob is @internalsref{Rest}. Whole bar rests centered in the bar are
 specified using @code{R}, see @ref{Multi measure rests}.
 

+For polyphonic music, it can be convenient to specify the rest position
+directly. You can do that by entering a note, with the keyword
+@code{\rest} appended, e.g. Rest collisions will leave these rests alone.
+
+@lilypond[singleline,verbatim]
+a'4\rest d'4\rest
+@end lilypond
+

 
 @c .  {Skips}
 @c FIXME: naming.
 
 @c .  {Skips}
 @c FIXME: naming.


@@ -310,8 +318,7 @@ The syntax for a verbose duration specification is
 @example
  \duration @var{scmduration}
 @end example
 @example
  \duration @var{scmduration}
 @end example

-Here, @var{scmduration} is a Scheme object of type @code{Duration}. See
-@ref{Duration} for more information.
+Here, @var{scmduration} is a Scheme object of type @code{Duration}.

 
 
 In Note, Chord, and Lyrics mode, durations may be designated by numbers
 
 
 In Note, Chord, and Lyrics mode, durations may be designated by numbers


@@ -847,8 +854,25 @@ a measure it is set to @code{defaultBarType}. The contents of
 @cindex polyphony
 
 Polyphonic parts, i.e. parts with more than one voice on a staff can be
 @cindex polyphony
 
 Polyphonic parts, i.e. parts with more than one voice on a staff can be

-typeset with LilyPond.   To use this, instantiate a separate Voice
-context for each part, and assign a stem direction to each part. 
+typeset with LilyPond.
+
+The easiest way to enter such fragments, is the Scheme function
+@code{voicify-music}. It will split chords using the separator
+@code{\\}, to make multiple voices.  You can use it for small,
+short-lived voices (make a chord of voices) or for single chords:
+
+@lilypond[verbatim,fragment]
+\context Voice = VA \apply #voicify-music \relative c'' {
+ c4 < { f d e  } \\ { b c2 } > c4 < g' \\ c, \\  f \\ d >
+}
+@end lilypond
+
+The function @code{voicify-music} instantiates @internalsref{Voice}
+contexts, bearing the names @code{"1"}, @code{"2"}, etc.
+
+To explicity typeset polyphonic music, instantiate a separate Voice
+context for each part, and assign a stem direction to each part.
+@c

 @lilypond[fragment,verbatim]
 \context Staff
 < \context Voice = VA { \stemUp b'4 a' g' f' e' }
 @lilypond[fragment,verbatim]
 \context Staff
 < \context Voice = VA { \stemUp b'4 a' g' f' e' }


@@ -913,8 +937,10 @@ LilyPond also vertically shifts rests that are opposite of a stem.
 @end lilypond
 
 Note head collisions (horizontal shifting of note heads) are handled by
 @end lilypond
 
 Note head collisions (horizontal shifting of note heads) are handled by

-the @internalsref{NoteCollision} grob. @internalsref{RestCollision} handles vertical
-shifting of rests.
+the @internalsref{NoteCollision} grob. @internalsref{RestCollision}
+handles vertical shifting of rests.
+
+

 
 
 
 
 
 


@@ -1080,12 +1106,18 @@ Set @code{height} to zero, to get horizontal beams:
 Here's how you'd specify a weird looking beam that instead of being
 horizontal, falls two staff spaces:
 
 Here's how you'd specify a weird looking beam that instead of being
 horizontal, falls two staff spaces:
 

+
+[FIXME]
+
+

 @lilypond[fragment,relative,verbatim]
   \property Voice.Beam \set #'staff-position = #4
   \property Voice.Beam \set #'height = #-4
   [c8 c] 
 @end lilypond
 
 @lilypond[fragment,relative,verbatim]
   \property Voice.Beam \set #'staff-position = #4
   \property Voice.Beam \set #'height = #-4
   [c8 c] 
 @end lilypond
 

+[TODO: doc autokneeing ? ]
+

 @c TODO -> why this ref? Document? 
 @cindex @code{neutral-direction}
 
 @c TODO -> why this ref? Document? 
 @cindex @code{neutral-direction}
 


@@ -1338,9 +1370,11 @@ To save typing work, some shorthands are available:
 
 @cindex fingering
 
 
 @cindex fingering
 

-Fingering instructions can also be entered in  this shorthand.
+Fingering instructions can also be entered in  this shorthand. For
+changes, some markup texts would be needed:

 @lilypond[verbatim, singleline, fragment]
       c'4-1 c'4-2 c'4-3 c'4-4
 @lilypond[verbatim, singleline, fragment]
       c'4-1 c'4-2 c'4-3 c'4-4

+      c^#'(finger "2-3")

 @end lilypond
 
 
 @end lilypond
 
 


@@ -1422,7 +1456,7 @@ Unbeamed eighth notes and shorter by default have a slash through the
 stem.
 
 @lilypond[fragment,verbatim]
 stem.
 
 @lilypond[fragment,verbatim]

-\relative c'' {
+\relative c'' \context Voice {

   \grace c8 c4 \grace { [c16 c16] } c4
   \grace { 
     \property Voice.Stem \override #'flag-style = #'() 
   \grace c8 c4 \grace { [c16 c16] } c4
   \grace { 
     \property Voice.Stem \override #'flag-style = #'() 


@@ -1602,6 +1636,7 @@ Make beat or measure repeats. These look like percent signs.
 
 @menu
 * Repeat syntax::               
 
 @menu
 * Repeat syntax::               

+* Repeats and MIDI::            

 * Manual repeat commands::      
 * Tremolo repeats::             
 * Tremolo subdivisions::        
 * Manual repeat commands::      
 * Tremolo repeats::             
 * Tremolo subdivisions::        


@@ -1664,11 +1699,13 @@ the specified number of repeats.
 }
 @end lilypond
 
 }
 @end lilypond
 

-@subsection Unfolding repeats for MIDI output.
+@node Repeats and MIDI
+@subsection Repeats and MIDI

 
 @cindex expanding repeats
 
 
 @cindex expanding repeats
 

-See @file{input/test/unfold-all-repeats.ly}. 
+For instructions on how to unfoldi repeats for MIDI output, see
+the example file @file{input/test/unfold-all-repeats.ly}.

 
 
 @refbugs
 
 
 @refbugs


@@ -1786,7 +1823,7 @@ patterns that divide the measure length are replaced by slashes.
  \context Voice { \repeat  "percent" 4  { c'4 }
     \repeat "percent" 2 { c'2 es'2 f'4 fis'4 g'4 c''4 }
 }
  \context Voice { \repeat  "percent" 4  { c'4 }
     \repeat "percent" 2 { c'2 es'2 f'4 fis'4 g'4 c''4 }
 }

-@end lilypond
+@end lilypond   

 
 The signs are represented by these grobs: @internalsref{RepeatSlash} and
 @internalsref{PercentRepeat} and @internalsref{DoublePercentRepeat}.
 
 The signs are represented by these grobs: @internalsref{RepeatSlash} and
 @internalsref{PercentRepeat} and @internalsref{DoublePercentRepeat}.


@@ -1847,13 +1884,16 @@ other pianistic peculiarities.
 Voices can switch automatically between the top and the bottom
 staff. The syntax for this is
 @example
 Voices can switch automatically between the top and the bottom
 staff. The syntax for this is
 @example

-        \autochange @var{contexttype} @var{musicexp}
+        \autochange @var{contexttype} \context @var{childcontexttype}
+               @var{musicexp} 

 @end example
 @end example

-This will switch the interpretation context of @var{musicexp} between a
-@var{contexttype} named @code{up} and @code{down}. Typically, you use
-@internalsref{Staff} for @var{contexttype}.  The autochanger switches on basis
-of pitch (central C is the turning point), and it looks ahead skipping
-over rests to switch rests in advance.
+@c
+This will switch the interpretation context of @var{musicexp} between
+a @var{contexttype} named @code{up} and @code{down}. Typically, you
+use @internalsref{Staff} for @var{contexttype}, and
+@internalsref{Voice} for @var{childcontexttype}. The autochanger
+switches on basis of pitch (central C is the turning point), and it
+looks ahead skipping over rests to switch rests in advance.

         
 @lilypond[verbatim,singleline]
 \score { \notes \context PianoStaff <
         
 @lilypond[verbatim,singleline]
 \score { \notes \context PianoStaff <


@@ -1915,15 +1955,45 @@ c''4 \spanrequest \stop "Sustain"
 @end lilypond
 
 The symbols that are printed can be modified by setting
 @end lilypond
 
 The symbols that are printed can be modified by setting

-@code{pedal@var{X}Strings}, where @var{X} is one of the pedal
-types. Refer to the generated documentation of @rgrob{PianoPedal} for
-more information.
+@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.

 
 

-@refbugs
+Pedals can also be indicated by a sequence of brackets, by setting the 
+@code{pedal-type} property of SustainPedal grobs: 
+
+@lilypond[fragment,verbatim]
+\property Staff.SustainPedal \override #'pedal-type = #'bracket
+c''4 \sustainDown d''4 e''4 a'4 \sustainUp \sustainDown f'4 g'4 a'4 \sustainUp
+@end lilypond
+
+A third style of pedal notation is a mixture of text and brackets,
+obtained by setting @code{pedal-type} to @code{mixed}:
+
+@lilypond[fragment,verbatim]
+\property Staff.SustainPedal \override #'pedal-type = #'mixed
+c''4 \sustainDown d''4 e''4 c'4 \sustainUp \sustainDown f'4 g'4 a'4 \sustainUp
+@end lilypond

 
 

+The default '*Ped' style for sustain and damper pedals corresponds to
+@code{\pedal-type = #'text}. However, @code{mixed} is the default style
+for a sostenuto pedal:
+
+@lilypond[fragment,verbatim]
+c''4 \sostenutoDown d''4 e''4 c'4 f'4 g'4 a'4 \sostenutoUp
+@end lilypond
+
+For fine-tuning of the appearance of a pedal bracket, the properties
+@code{edge-width}, @code{edge-height}, and @code{shorten-pair} of
+@code{PianoPedalBracket} grobs (see the detailed documentation of
+@rgrob{PianoPedalBracket}) can be modified.  For example, the bracket
+may be extended to the end of the note head.
+
+@lilypond[fragment,verbatim]
+\property Staff.PianoPedalBracket \override #'shorten-pair = #'(0 . -1.0)
+c''4 \sostenutoDown d''4 e''4 c'4 f'4 g'4 a'4 \sostenutoUp
+@end lilypond

 
 

-Currently, brackets are not supported, only text markings (i.e. `*Ped'
-style).

 
 
 @c .   {Arpeggio}
 
 
 @c .   {Arpeggio}


@@ -1955,7 +2025,7 @@ to the chords in both staves, and set
 @end lilypond
 
 This command creates @internalsref{Arpeggio} grobs.  Cross staff arpeggios
 @end lilypond
 
 This command creates @internalsref{Arpeggio} grobs.  Cross staff arpeggios

-are @code{PianoStaff.Arpeggio}. @internalsref{Arpeggio}
+are @code{PianoStaff.Arpeggio}.

 
 To add an arrow head to explicitly specify the direction of the
 arpeggio, you should set the arpeggio grob property
 
 To add an arrow head to explicitly specify the direction of the
 arpeggio, you should set the arpeggio grob property


@@ -1970,19 +2040,20 @@ arpeggio, you should set the arpeggio grob property
   }
 @end lilypond
 
   }
 @end lilypond
 

-@ignore

 A square bracket on the left indicates that the player should not
 A square bracket on the left indicates that the player should not

-arpeggiate the chord.
+arpeggiate the chord. To draw these brackets, set the
+@code{molecule-callback} property of @code{Arpeggio} or
+@code{PianoStaff.Arpeggio} grobs to @code{\arpeggioBracket}, and use
+@code{\arpeggio} statements within the chords as before.

 
 

-@lil ypond[fragment,relative,verbatim]
+@lilypond[fragment,relative,verbatim]

   \context PianoStaff <
     \property PianoStaff.connectArpeggios = ##t
   \context PianoStaff <
     \property PianoStaff.connectArpeggios = ##t

-    \property PianoStaff.Arpeggio \override #'arpeggio-direction = #'bracket
+    \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'\arpeggio e g c> }
     \context Voice = other { \clef bass  <c,,\arpeggio e g>}
   >  

-@ e nd lilypond
-@end ignore
+@end lilypond

 
 
 @refbugs
 
 
 @refbugs


@@ -2838,6 +2909,15 @@ block:
 @}
 @end example
 
 @}
 @end example
 

+
+@c . {Figured bass}
+@node Figured bass
+@section Figured bass
+
+@cindex Basso continuo
+
+TODO. see figured-bass.ly
+

 @c . {Tuning output}
 @node Tuning output
 @section Tuning output
 @c . {Tuning output}
 @node Tuning output
 @section Tuning output


@@ -3139,8 +3219,10 @@ Type1 usually come as ``one design fits all sizes''.
 @code{cmti}, etc. Setting this overrides font-family, font-shape and
 font-series.
 
 @code{cmti}, etc. Setting this overrides font-family, font-shape and
 font-series.
 

+

 @end table
 
 @end table
 

+

 The font is selected by taking the first font that satisfies all
 qualifiers specified. You can override any of these fields through
 @code{\override} and @code{\revert}. The special value @code{*} matches
 The font is selected by taking the first font that satisfies all
 qualifiers specified. You can override any of these fields through
 @code{\override} and @code{\revert}. The special value @code{*} matches


@@ -3163,14 +3245,20 @@ and @code{dynamic}.
 The style sheets and tables for selecting fonts are located in
 @file{scm/font.scm}. Refer to this file for more information.
 
 The style sheets and tables for selecting fonts are located in
 @file{scm/font.scm}. Refer to this file for more information.
 

+
+Setting @code{font-name} overrides all other qualifiers. The value for
+this property should be a string, the file name of the font. You may use
+this to use special fonts, which are not a part of the style sheet, or
+which have special encodings.
+
+The size of the font may be set with the grob property
+@code{font-magnification}.  It is the size of font, relative to its
+standard size. For example, @code{1.0} is normal size.
+

 @refbugs
 
 Relative size is not linked to any real size.
 
 @refbugs
 
 Relative size is not linked to any real size.
 

-There is no mechanism to select magnification of particular fonts,
-meaning that you don't have access to continuously scaled fonts.  You
-can scale the entire output, of course, see @ref{Output scaling}.
-

 There is no style sheet provided for other fonts besides the @TeX{}
 family.
 
 There is no style sheet provided for other fonts besides the @TeX{}
 family.
 


@@ -3512,19 +3600,25 @@ You may enter these dimension using units (@code{cm}, @code{in},
 @c .  {Font size}
 @node Font Size
 @subsection Font size
 @c .  {Font size}
 @node Font Size
 @subsection Font size

-@cindex font size
+@cindex font size, setting
+@cindex staff size, setting
+@cindex @code{paper} file

 
 The Feta font provides musical symbols at six different sizes.  These
 
 The Feta font provides musical symbols at six different sizes.  These

-fonts are 11 point, 13 point, 16 point, 20 point,
-23 point, and 26 point.  The point size of a font is the
-height of the five lines in a staff when displayed in the font.
+fonts are 11 point, 13 point, 16 point, 20 point, 23 point, and 26
+point.  The point size of a font is the height of the five lines in a
+staff when displayed in the font.

 
 Definitions for these sizes are the files @file{paperSZ.ly}, where
 @code{SZ} is one of 11, 13, 16, 20, 23 and 26.  If you include any of
 these files, the identifiers @code{paperEleven}, @code{paperThirteen},
 @code{paperSixteen}, @code{paperTwenty}, @code{paperTwentythree}, and
 @code{paperTwentysix} are defined respectively.  The default
 
 Definitions for these sizes are the files @file{paperSZ.ly}, where
 @code{SZ} is one of 11, 13, 16, 20, 23 and 26.  If you include any of
 these files, the identifiers @code{paperEleven}, @code{paperThirteen},
 @code{paperSixteen}, @code{paperTwenty}, @code{paperTwentythree}, and
 @code{paperTwentysix} are defined respectively.  The default

-@code{\paper} block is also set.
+@code{\paper} block is also set. These files should be imported at toplevel, i.e.
+@example
+       \include "paper26.ly"
+       \score @{  ... @}
+@end example

 
 The font definitions are generated using a Scheme function. For more
 details, see the file @file{scm/font.scm}.
 
 The font definitions are generated using a Scheme function. For more
 details, see the file @file{scm/font.scm}.


@@ -3563,8 +3657,8 @@ Lilypond and @code{ly2dvi})
 @cindex breaking lines
 
 Line breaks are normally computed automatically. They are chosen such
 @cindex breaking lines
 
 Line breaks are normally computed automatically. They are chosen such

-that the resulting spacing has low variation, and looks neither cramped
-nor loose.
+that it looks neither cramped nor loose, and that consecutive lines have
+similar density.

 
 Occasionally you might want to override the automatic breaks; you can do
 this by specifying @code{\break}. This will force a line break at this
 
 Occasionally you might want to override the automatic breaks; you can do
 this by specifying @code{\break}. This will force a line break at this


@@ -3573,6 +3667,17 @@ are bar lines.  If you want to have a line break where there is no
 bar line, you can force an invisible bar line by entering @code{\bar
 ""}. Similarly, @code{\noBreak} forbids a line break at a certain point.
 
 bar line, you can force an invisible bar line by entering @code{\bar
 ""}. Similarly, @code{\noBreak} forbids a line break at a certain point.
 

+If you want linebreaks at regular intervals, you can use the following:
+@example
+
+<  \repeat 7 unfold @{ s1 * 4 \break  @}
+   @emph{real music}
+> 
+@end  example
+This makes the following 28 measures (assuming 4/4 time) be broken every
+4 measures.
+
+

 @cindex @code{\penalty}
 
 The @code{\break} and @code{\noBreak} commands are defined in terms of
 @cindex @code{\penalty}
 
 The @code{\break} and @code{\noBreak} commands are defined in terms of


@@ -4574,8 +4679,7 @@ including dimensions.  Produced by some Grob functions
 See @ref{Molecules}
 @item Translator: object that produces audio objects or Grobs. This is
 not yet user accessible.
 See @ref{Molecules}
 @item Translator: object that produces audio objects or Grobs. This is
 not yet user accessible.

-@item Font_metric: object representing a font. (See @ref{Font metrics})
-
+@item Font_metric: object representing a font.

 @end itemize
 
 
 @end itemize
 
 


@@ -5035,16 +5139,16 @@ See @ref{convert-ly} for more information on @code{convert-ly}.
 
 
 
 
 
 

-
-@c .{Local emacs vars}
-@c Local variables:
-@c mode: texinfo
-@c minor-mode: font-lock
-@c minor-mode: outline
-@c outline-layout: (-1 : 0)
-@c outline-use-mode-specific-leader: "@c \."
-@c outline-primary-bullet: "{"
-@c outline-stylish-prefixes: nil
-@c outline-override-protect: t
+@c broken with  emacs-21
+@c {Local emac s  vars}
+@c Local varia bles:
+@c mode: texi nfo
+@c minor-mod e: font-lock
+@c minor-mo de: outline
+@c outline -layout: (-1 : 0)
+@c outlin e-use-mode-specific-leader: "@c \."
+@c outli ne-primary-bullet: "{"
+@c outli ne-stylish-prefixes: nil
+@c outli ne-override-protect: t

 @c End:
 
 @c End: