]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/user/refman.itely
nu wel 58
[lilypond.git] / Documentation / user / refman.itely
index 2dcb3514404d915183841eededb26bb06e342bca..8833e029d86b407834bae9421878f157bc66f482 100644 (file)
@@ -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
@@ -68,6 +67,7 @@ syntactical details are described at the end of the manual.
 * Chords::                      
 * Writing parts::               
 * Custodes::                    
+* Figured bass::                
 * Tuning output::               
 * Page layout::                 
 * Output formats::              
@@ -194,7 +194,7 @@ The verbose syntax for pitch specification is
   \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
@@ -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}.
 
+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.
@@ -310,8 +318,7 @@ The syntax for a verbose duration specification is
 @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
@@ -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
-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' }
@@ -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
-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:
 
+
+[FIXME]
+
+
 @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}
 
@@ -1199,7 +1231,10 @@ c'4 \breathe d4
 
 @refbugs
 
-  Currently, only tick marks are supported, not comma style breath marks.
+The current layout of the default comma style breath marks
+could be improved and more optional symbols should be added to the
+font.
+
 
 
 @c .  {Tempo}
@@ -1335,9 +1370,11 @@ To save typing work, some shorthands are available:
 
 @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
+      c^#'(finger "2-3")
 @end lilypond
 
 
@@ -1419,7 +1456,7 @@ Unbeamed eighth notes and shorter by default have a slash through the
 stem.
 
 @lilypond[fragment,verbatim]
-\relative c'' {
+\relative c'' \context Voice {
   \grace c8 c4 \grace { [c16 c16] } c4
   \grace { 
     \property Voice.Stem \override #'flag-style = #'() 
@@ -1553,9 +1590,15 @@ For everyday use, we recommend the identifiers @code{\cresc},
 @cindex diminuendo
 
 Dynamics are grobs of @internalsref{DynamicText} and
-@internalsref{Hairpin}. They are put together on
-@internalsref{DynamicLineSpanner} to align them vertically.
+@internalsref{Hairpin}. Vertical positioning of these symbols is handled
+by the @internalsref{DynamicLineSpanner} grob.  If you want to adjust
+padding or vertical direction of the dynamics, you must set properties
+for the @internalsref{DynamicLineSpanner} grob. Predefined identifiers
+to set the vertical direction are \dynamicUp and \dynamicDown.
 
+@cindex direction, of dynamics
+@cindex @code{\dynamicDown}
+@cindex @code{\dynamicUp}
 
 @c .  {Repeats}
 @node Repeats
@@ -1593,6 +1636,7 @@ Make beat or measure repeats. These look like percent signs.
 
 @menu
 * Repeat syntax::               
+* Repeats and MIDI::            
 * Manual repeat commands::      
 * Tremolo repeats::             
 * Tremolo subdivisions::        
@@ -1655,11 +1699,13 @@ the specified number of repeats.
 }
 @end lilypond
 
-@subsection Unfolding repeats for MIDI output.
+@node Repeats and MIDI
+@subsection Repeats and MIDI
 
 @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
@@ -1777,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 }
 }
-@end lilypond
+@end lilypond   
 
 The signs are represented by these grobs: @internalsref{RepeatSlash} and
 @internalsref{PercentRepeat} and @internalsref{DoublePercentRepeat}.
@@ -1838,13 +1884,16 @@ other pianistic peculiarities.
 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
-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 <
@@ -1906,15 +1955,45 @@ c''4 \spanrequest \stop "Sustain"
 @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}
@@ -1946,7 +2025,7 @@ to the chords in both staves, and set
 @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
@@ -1961,19 +2040,20 @@ arpeggio, you should set the arpeggio grob property
   }
 @end lilypond
 
-@ignore
 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
-    \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>}
   >  
-@ e nd lilypond
-@end ignore
+@end lilypond
 
 
 @refbugs
@@ -2829,6 +2909,15 @@ block:
 @}
 @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
@@ -3130,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.
 
+
 @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
@@ -3154,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.
 
+
+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.
 
-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.
 
@@ -3503,19 +3600,25 @@ You may enter these dimension using units (@code{cm}, @code{in},
 @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
-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
-@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}.
@@ -3532,19 +3635,19 @@ details, see the file @file{scm/font.scm}.
 @cindex @code{papersize}
 
 To change the paper size, you must first set the
-@code{papersize} variable at top level.  Set it to
+@code{papersize} paper variable variable.  Set it to
 the strings @code{a4}, @code{letter}, or @code{legal}.  After this
 specification, you must set the font as described above.  If you want
 the default font, then use the 20 point font.
 
 @example
-        papersize = "a4"
+        \paper@{ papersize = "a4" @}
         \include "paper16.ly"
 @end example
 
 The file @code{paper16.ly}  will now include a file named @file{a4.ly}, which
 will set the paper variables @code{hsize} and @code{vsize} (used by
-@code{ly2dvi})
+Lilypond and @code{ly2dvi})
 
 @c .  {Line break}
 @node Line break
@@ -3554,8 +3657,8 @@ will set the paper variables @code{hsize} and @code{vsize} (used by
 @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
@@ -3564,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.
 
+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
@@ -3977,11 +4091,17 @@ A bar check is entered using the bar symbol, @code{|}:
   \time 3/4 c2 e4 | g2.
 @end example
 
+
+
 @cindex skipTypesetting
 
-Bar checks are not affected by @code{skipTypesetting}, so if you are
-debugging a large score, you are advised to run it with skipTypesetting
-first to correct all overfull and underfull measures.
+Failed bar checks are most often caused by entering incorrect
+durations. Incorrect durations often completely garble up the score,
+especially if it is polyphonic, so you should start correcting the score
+by scanning for failed bar checks and incorrect durations.  To speed up
+this process, you can use @code{skipTypesetting} (See @ref{Skipping
+corrected music})). Bar
+
 
 @c .  {Point and click}
 @node Point and click
@@ -4559,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.
-@item Font_metric: object representing a font. (See @ref{Font metrics})
-
+@item Font_metric: object representing a font.
 @end itemize
 
 
@@ -5020,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: