po-replace

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

diff --git a/Documentation/user/refman.itely b/Documentation/user/refman.itely
index cc22005e4b8b15924a1cbca3f37da61e7a5c562d..25ca7c6cd6f4bf3417a76f9c8bc1a0e7a91218df 100644 (file)
--- a/Documentation/user/refman.itely
+++ b/Documentation/user/refman.itely
@@ -1,6 +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


@@ -29,9 +27,8 @@ See @internalsref{\NAME\}
 @macro seeinternals{NAME}
 @end macro
 @macro internalsref{NAME}
 @macro seeinternals{NAME}
 @end macro
 @macro internalsref{NAME}

-\NAME\

 @cindex \NAME\
 @cindex \NAME\

-
+\NAME\

 @end macro
 @end ifnothtml
 
 @end macro
 @end ifnothtml
 


@@ -49,137 +46,71 @@ revision of this document was made for LilyPond 1.4.1.  It supposes a
 passing familiarity with how LilyPond input works. New users are
 encouraged to study the tutorial first.
 
 passing familiarity with how LilyPond input works. New users are
 encouraged to study the tutorial first.
 

-The reference manual is ordered according to different tasks. 
-More details on the property setting mechanisms and context handling is
-provided in @ref{Tuning output} and @ref{Interpretation context}. The
-syntactical details are described at the end of the manual.

 
 @menu
 
 @menu

-* Overview::                   
-* Note entry::                 
-* Staff notation::             
-* Polyphony::                  
-* Beaming::                    
-* Expressive marks::           
-* Ornaments::                  
-* Repeats::                    
-* Rhythmic music::             
-* Piano music::                        
-* Lyrics::                     
-* Chords::                     
-* Writing parts::              
-* Custodes::                   
-* Figured bass::               
-* Tuning output::              
-* Page layout::                        
-* Output formats::             
-* Sound::                      
-* Music entry::                        
-* Skipping corrected music::   
-* Interpretation context::     
-* Syntactic details::          
-* Lexical details::            
+* Note entry::                  
+* Staff notation::              
+* Polyphony::                   
+* Beaming::                     
+* Expressive marks::            
+* Ornaments::                   
+* Repeats::                     
+* Rhythmic music::              
+* Piano music::                 
+* Tablatures::                 
+* Lyrics::                      
+* Chords::                      
+* Writing parts::               
+* Ancient notation ::           
+* Ancient clefs ::              
+* Figured bass::                
+* Tuning output::               
+* Page layout::                 
+* Output formats::              
+* Sound::                       
+* Music entry::                 
+* Skipping corrected music::    
+* Interpretation context::      
+* Syntactic details::           
+* Lexical details::             

 @end menu
 
 @end menu
 

-@c . {Overview}
-@node Overview
-@section Overview
-
-
-The purpose of LilyPond is explained informally by the term `music
-typesetter'.  This is not a fully correct name: not only does the
-program print musical symbols, it also makes aesthetic decisions.
-Symbols and their placements are @emph{generated} from a high-level
-musical description.  In other words, LilyPond would be best described
-by `music compiler' or `music to notation compiler'.
-
-LilyPond is linked to GUILE, GNU's Scheme library for extension
-programming. The Scheme library provides the glue that holds together
-the low-level routines and separate modules which are written in C++.
-
-When lilypond is run to typeset sheet music, the following happens:
-@itemize @bullet
-@item GUILE Initialization: various scheme files are read
-@item parsing: first standard @code{ly} initialization  files are read, and
-then the user @file{ly} file is read.
-@item interpretation: the music in the file is processed ``in playing
-order'', i.e. the order that  you  use to read sheet music, or the
-order in which notes are played. The result of this step is a typesetting
-specification.
-
-@item typesetting:
-The typesetting specification is solved: positions and formatting is
-calculated.
-
-@item the visible results ("virtual ink") are written to the output file.
-@end itemize
-
-During these stages different types of data play the the main role:
-during parsing, @strong{Music} objects are created.  During the
-interpretation, @strong{contexts} are constructed, and with these contexts
-a network of @strong{graphical objects} (``grobs'') is created. These
-grobs contain unknown variables, and the network forms a set of
-equations. After solving the equations and filling in these variables,
-the printed output (in the form of @strong{molecules}) is written to an
-output file.
-
-These threemanship of tasks (parsing, translating, typesetting) and
-data-structures (music, context, graphical objects) permeates the entire
-design of the program.
-

 @c FIXME: Note entry vs Music entry at top level menu is confusing.
 @c . {Note entry}
 @node Note entry
 @section Note entry
 @cindex Note entry
 
 @c FIXME: Note entry vs Music entry at top level menu is confusing.
 @c . {Note entry}
 @node Note entry
 @section Note entry
 @cindex Note entry
 

-The most basic forms of music are notes. We discuss how you enter them
-here.  Notes on their own don't form valid input, but for the sake of
-brevity we omit obligatory lint such as @code{\score} blocks and
-@code{\paper} declarations.
+The most basic forms of music are notes.  Notes on their own don't
+form valid input, but for the sake of brevity we omit @code{\score}
+blocks and @code{\paper} declarations.

 
 
 @menu
 
 
 @menu

-* Notes::                      
-* Pitches::                    
-* Rests::                      
-* Skips::                      
-* Durations::                  
-* Ties::                       
-* Tuplets::                    
-* Defining pitch names::       
-* Easy Notation note heads ::  
+* Notes::                       
+* Pitches::                     
+* Chromatic alterations::       
+* Rests::                       
+* Skips::                       
+* Durations::                   
+* Ties::                        
+* Automatic note splitting ::   
+* Tuplets::                     
+* Defining pitch names::        
+* Easy Notation note heads ::   

 @end menu
 
 @c . {Notes}
 @node Notes
 @subsection Notes
 
 @end menu
 
 @c . {Notes}
 @node Notes
 @subsection Notes
 

-A note specification has the form

 
 

-@example
-  @var{pitch}[!][?][@var{duration}]
-@end example
-
-The alteration refers to what note is heard, not to whether an
-accidental is printed. This is done depending on the key and context.
-A reminder accidental
-@cindex reminder accidental
-@cindex @code{?}
-can be forced by adding an exclamation mark @code{!} after the pitch.  A
-cautionary accidental,
-@cindex cautionary accidental
-@cindex parenthesized accidental
-i.e., an accidental within parentheses can be obtained by adding the
-question mark `@code{?}' after the pitch.
-
-@lilypond[fragment,verbatim,center]
-  cis' d' e' cis'  c'? d' e' c'!
+A note is printed by specifying its pitch, and then its duration.
+@lilypond[fragment,verbatim]
+  cis'4 d'8 e'16 c'16

 @end lilypond
 @end lilypond

-

 The grob for a note head is called @internalsref{NoteHead}.
 
 The grob for a note head is called @internalsref{NoteHead}.
 

-

 @c .  {Pitches}
 @node Pitches
 @subsection Pitches
 @c .  {Pitches}
 @node Pitches
 @subsection Pitches


@@ -242,6 +173,27 @@ octave; each @code{,} lowers the pitch by an octave.
   c' c'' es' g' as' gisis' ais'  
 @end lilypond
 
   c' c'' es' g' as' gisis' ais'  
 @end lilypond
 

+@node Chromatic alterations
+@subsection Chromatic alterations
+
+Normally Accidentals signify that the pitch of a note differs from the
+key signature. Normally, they are printed automatically depending, but
+you may force accidentals in the following  ways:
+A reminder accidental
+@cindex reminder accidental
+@cindex @code{?}
+can be forced by adding an exclamation mark @code{!} after the pitch.  A
+cautionary accidental,
+@cindex cautionary accidental
+@cindex parenthesized accidental
+i.e., an accidental within parentheses can be obtained by adding the
+question mark `@code{?}' after the pitch.
+
+Each accidental symbol is an @internalsref{Accidental} grob. The
+placement of accidentals is handled by
+@internalsref{AccidentalPlacement}.
+
+

 @c .  {Rests}
 @node  Rests
 @subsection Rests
 @c .  {Rests}
 @node  Rests
 @subsection Rests


@@ -274,13 +226,14 @@ a'4\rest d'4\rest
 @cindex Space note
 
 An invisible rest, or skip, can be entered like a note with note name
 @cindex Space note
 
 An invisible rest, or skip, can be entered like a note with note name

-`@code{s}':
+@code{s}, or with @code{\skip @var{duration}}:

 
 @lilypond[singleline,verbatim]
 
 @lilypond[singleline,verbatim]

-a2 s4 a4 s1 a4
+a2 s4 a4 \skip 1 a4 

 @end lilypond
 
 @end lilypond
 

-Actually, this is a shorthand for the @code{\skip} command, and it is
+The @code{s} syntax  is only available in Note mode and Chord mode. 
+In other situations, you should use the @code{\skip} command, and it is

 only available in Note mode and Chord mode.
 
 @c FIXME: in lyrics mode, we have " " and _
 only available in Note mode and Chord mode.
 
 @c FIXME: in lyrics mode, we have " " and _


@@ -305,7 +258,8 @@ note mode:
 }
 @end lilypond
 
 }
 @end lilypond
 

-Note that the skip does not produce any output, not even transparent output.
+The skip command is merely a empty musical placeholder. It does not
+produce any output, not even transparent output.

 
 
 @c .  {Durations}
 
 
 @c .  {Durations}


@@ -355,16 +309,6 @@ r1 r2 r4 r8 r16 r32 r64 r64
 }
 @end lilypond
 
 }
 @end lilypond
 

- To get a longa note head, you have to use mensural note heads. This
-is accomplished by setting the @code{style} property of the
-NoteHead grob to @code{mensural}. There is also a note head style
-@code{baroque} which gives mensural note heads for @code{\longa} and
-@code{\breve} but standard note heads for shorter notes.
-
-@lilypond[fragment,singleline,verbatim]
- \property Voice.NoteHead \set #'style = #'mensural
- a'\longa
-@end lilypond

 
 If the duration is omitted then it is set to the previous duration
 entered.  At the start of parsing a quarter note is assumed.  The
 
 If the duration is omitted then it is set to the previous duration
 entered.  At the start of parsing a quarter note is assumed.  The


@@ -392,19 +336,21 @@ will not affect the appearance of the notes or rests produced.
 @cindex ties
 @cindex @code{~}
 
 @cindex ties
 @cindex @code{~}
 

-A tie connects two adjacent note heads of the same pitch.  When used
-with chords, it connects all the note heads whose pitches match.
-Ties are indicated using the tilde symbol `@code{~}'.  If you try to tie
-together chords which have no common pitches then no ties will be
-created.
+A tie connects two adjacent note heads of the same pitch.  The tie in
+effect extends the length of a note. A tie is entered with @code{~}.

 
 @lilypond[fragment,verbatim,center]
   e' ~ e' <c' e' g'> ~ <c' e' g'>
 @end lilypond
 
 
 @lilypond[fragment,verbatim,center]
   e' ~ e' <c' e' g'> ~ <c' e' g'>
 @end lilypond
 

-If you dislike the amount of ties created for a chord, you set
-@code{Voice.sparseTies} to true, resulting in  a smaller number of
-ties:
+When ties are used with chords, all note heads whose pitches match are
+connected.  Ties are indicated using the tilde symbol `@code{~}'.  If
+you try to tie together chords which have no common pitches then no
+ties will be created.
+
+If you want less  ties created for a chord, you can  set
+@code{Voice.sparseTies} to true. In this case, a single tie is used
+for every tied chord.

 @lilypond[fragment,verbatim,center]
   \property Voice.sparseTies = ##t
   <c' e' g'> ~ <c' e' g'>
 @lilypond[fragment,verbatim,center]
   \property Voice.sparseTies = ##t
   <c' e' g'> ~ <c' e' g'>


@@ -417,6 +363,8 @@ exactly the same concept.
 @lilypond[fragment, singleline]
 \time 3/4 c'2. c'2 ~ c'4
 @end lilypond
 @lilypond[fragment, singleline]
 \time 3/4 c'2. c'2 ~ c'4
 @end lilypond

+Ties should not be confused with slurs, which indicate articulation,
+and phrasing slurs, which indicate musical phrasing.

 
 The name of the tie grob is @internalsref{Tie}, and it is created in the
 @internalsref{Voice} context.
 
 The name of the tie grob is @internalsref{Tie}, and it is created in the
 @internalsref{Voice} context.


@@ -424,13 +372,39 @@ The name of the tie grob is @internalsref{Tie}, and it is created in the
 @refbugs
 
 At present, the tie is implemented as a separate thing, temporally
 @refbugs
 
 At present, the tie is implemented as a separate thing, temporally

-located in between the notes. There is also no way to convert
-between tied notes, dotted notes and plain notes.
-
+located in between the notes. 

 Tieing only a subset of the note heads of a chord is not supported in a
 simple way.  It can be achieved by moving the tie-engraver into the Thread
 context and turning on and off ties per Thread.
 
 Tieing only a subset of the note heads of a chord is not supported in a
 simple way.  It can be achieved by moving the tie-engraver into the Thread
 context and turning on and off ties per Thread.
 

+@node Automatic note splitting 
+@subsection Automatic note splitting
+
+There is a facility for automatically converting long notes to  tied
+notes. This is done by replacing the @code{Note_heads_engraver} by the
+@code{Completion_heads_engraver}. 
+
+@lilypond[verbatim,center]
+\score{
+  \notes\relative c'{ \time 2/4
+  c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2 
+  }
+  \paper{ \translator{
+      \ThreadContext
+      \remove "Note_heads_engraver"
+      \consists "Completion_heads_engraver"
+  } } }
+@end lilypond
+
+This engraver splits all running notes at the bar line, and inserts
+ties. One of the uses of this is, is to debug complex scores: if the
+measures are not entirely filled, then the ties exactly show how much
+each measure is off.
+
+@refbugs
+
+Not all durations (especially those containing tuplets) can be
+represented exactly; the engraver will not insert tuplets. 

 
 @node Tuplets
 @subsection Tuplets
 
 @node Tuplets
 @subsection Tuplets


@@ -472,27 +446,31 @@ denominator, but if you set it to the Scheme function
 @code{fraction-tuplet-formatter}, Lilypond will print @var{num}:@var{den}
 instead.
 
 @code{fraction-tuplet-formatter}, Lilypond will print @var{num}:@var{den}
 instead.
 

+@c todo: junk this?
+

 The typesetting of brackets and numbers is controlled by the properties
 The typesetting of brackets and numbers is controlled by the properties

-@code{tuplet-bracket-visibility} and @code{tuplet-number-visibility}. 
+@code{bracket-visibility} and @code{number-visibility}.  These
+properties can either be @code{#f}, @code{#t} or @code{'if-no-beam},
+meaning respectively off, on, and on if there is no beam. 

 
 @lilypond[fragment,  relative, singleline, verbatim]
 
 @lilypond[fragment,  relative, singleline, verbatim]

-\property Voice.TupletBracket \set #'tuplet-bracket-visibility = ##t
+\property Voice.TupletBracket \set #'bracket-visibility = ##t

 \times 2/3{c'8 d e} \times 2/3{d4 e8} 
 \times 2/3{c'8 d e} \times 2/3{d4 e8} 

-\property Voice.TupletBracket \set #'tuplet-bracket-visibility = #'if-no-beam
+\property Voice.TupletBracket \set #'bracket-visibility = #'if-no-beam

 \times 2/3{c d e} \times 2/3{d4 e8} 
 \times 2/3{c d e} \times 2/3{d4 e8} 

-\property Voice.TupletBracket \set #'tuplet-bracket-visibility = ##f
+\property Voice.TupletBracket \set #'bracket-visibility = ##f

 \times 2/3{c d e} \times 2/3{d4 e8}
 \times 2/3{c d e} \times 2/3{d4 e8}

-\property Voice.TupletBracket \set #'tuplet-number-visibility = ##f
+\property Voice.TupletBracket \set #'number-visibility = ##f

 \times 2/3{c d e} \times 2/3{d4 e8}
 \times 2/3{c d e} \times 2/3{d4 e8}

-\property Voice.TupletBracket \set #'tuplet-number-visibility = #'if-no-beam
+\property Voice.TupletBracket \set #'number-visibility = #'if-no-beam

 \times 2/3{c d e} \times 2/3{d4 e8}
 @end lilypond
 
 @cindex @code{tupletNumberFormatFunction}
 @cindex tuplet formatting 
 
 \times 2/3{c d e} \times 2/3{d4 e8}
 @end lilypond
 
 @cindex @code{tupletNumberFormatFunction}
 @cindex tuplet formatting 
 

-Tuplet brackets are printed as @internalsref{TupletBracket} grobs, most
-often in the @internalsref{Voice} context.
+Tuplet brackets are printed as @internalsref{TupletBracket} grobs in
+the @internalsref{Voice} context.

 
 @c .  {Defining pitch names}
 @node Defining pitch names
 
 @c .  {Defining pitch names}
 @node Defining pitch names


@@ -511,7 +489,7 @@ syntax is as follows.
    \chordmodifiers @var{scheme-alist}
 @end example
 
    \chordmodifiers @var{scheme-alist}
 @end example
 

-See @file{ly/nederlands.ly} and @file{ly/chord-modifiers.ly} for
+See @file{ly/nederlands.ly} and @file{ly/chord-modifiers-init.ly} for

 specific examples on how to do this.
 
 
 specific examples on how to do this.
 
 


@@ -553,11 +531,11 @@ the @code{-f ps} option of lilypond produces the correct result.
 @cindex Staff notation
 
 @menu
 @cindex Staff notation
 
 @menu

-* Key signature::              
-* Clef::                       
-* Time signature::             
-* Unmetered music::            
-* Bar lines::                  
+* Key signature::               
+* Clef::                        
+* Time signature::              
+* Unmetered music::             
+* Bar lines::                   

 @end menu
 
 @c .  {Key}
 @end menu
 
 @c .  {Key}


@@ -604,25 +582,12 @@ created in @internalsref{Staff} context.
 @subsection Clef
 @cindex @code{\clef}
 
 @subsection Clef
 @cindex @code{\clef}
 

-The clef can be set or changed with the @code{\clef} command.
-@example
-  \clef @var{clefname}
-@end example
-
-Shortcut for
-
-@example
-  \property Staff.clefGlyph = @var{glyph associated with clefname} 
-  \property Staff.clefPosition = @var{clef Y-position for clefname}
-  \property Staff.centralCPosition = @var{position for central C} 
-  \property Staff.clefOctavation = @var{extra transposition of clefname}
-@end example
-
-
-Any change in these properties creates a clef (A @internalsref{Clef} grob).
+The clef can be set or changed with the @code{\clef} command:
+@lilypond[fragment,verbatim]
+  \key f\major  c''2 \clef alto g'2
+@end lilypond

 
 Supported clef-names include 
 
 Supported clef-names include 

-

 @c Moved standard clefs to the top /MB
 @table @code
 @item treble, violin, G, G2
 @c Moved standard clefs to the top /MB
 @table @code
 @item treble, violin, G, G2


@@ -655,55 +620,28 @@ enclose @var{clefname} in quotes if you use underscores or digits in the
 name. For example,
 @example
        \clef "G_8"
 name. For example,
 @example
        \clef "G_8"

-@end example 
+@end example

 
 

-Supported associated glyphs (for @code{Staff.clefGlyph}) are:
+The grob for this symbol is @internalsref{Clef}. 
+
+
+The full syntax for this command is 
+@example
+  \clef @var{clefname}
+@end example
+where @var{clefname} is a string. This command is a shortcut for
+@example
+  \property Staff.clefGlyph = @var{glyph associated with clefname} 
+  \property Staff.clefPosition = @var{clef Y-position for clefname}
+  \property Staff.centralCPosition = @var{position for central C} 
+  \property Staff.clefOctavation = @var{extra transposition of clefname}
+@end example
+Upon any change in these properties lilypond creates a clef
+symbol. The mapping from @var{clefname} to the property values can be
+found in @file{scm/clef.scm}

 
 

-@table @code
-@item clefs-C
- modern style C clef
-@item clefs-F
- modern style F clef
-@item clefs-G
- modern style G clef
-@item clefs-vaticana_do
- Editio Vaticana style do clef
-@item clefs-vaticana_fa
- Editio Vaticana style fa clef
-@item clefs-medicaea_do
- Editio Medicaea style do clef
-@item clefs-medicaea_fa
- Editio Medicaea style fa clef
-@item clefs-mensural1_c
- modern style mensural C clef
-@item clefs-mensural2_c
- historic style small mensural C clef
-@item clefs-mensural3_c
- historic style big mensural C clef
-@item clefs-mensural1_f
- historic style traditional mensural F clef
-@item clefs-mensural2_f
- historic style new mensural F clef
-@item clefs-mensural_g
- historic style mensural G clef
-@item clefs-hufnagel_do
- historic style hufnagel do clef
-@item clefs-hufnagel_fa
- historic style hufnagel fa clef
-@item clefs-hufnagel_do_fa
- historic style hufnagel combined do/fa clef
-@item clefs-percussion
- modern style percussion clef
-@end table

 
 

-@emph{Modern style} means ``as is typeset in current editions.''
-@emph{Historic style} means ``as was typeset or written in contemporary
-historic editions''.  @emph{Editio XXX style} means ``as is/was printed in
-Editio XXX.''

 
 

-@cindex Vaticana, Editio
-@cindex Medicaea, Editio
-@cindex hufnagel clefs

 
 
 @c .  {Time signature}
 
 
 @c .  {Time signature}


@@ -714,23 +652,10 @@ Editio XXX.''
 @cindex @code{\time}
 
 The time signature is set or changed by the @code{\time}
 @cindex @code{\time}
 
 The time signature is set or changed by the @code{\time}

-command. Syntax:
-@example
-  \time @var{n}@code{/}@var{d} 
-@end example
-Internally, this is a shortcut for doing
-@example
-\property Score.timeSignatureFraction = #'(@var{n} . @var{d})
-\property Score.beatLength = #(make-moment 1 @var{d})
-\property Score.measureLength = #(make-moment @var{n} @var{d})
-@end example
-
-These properties @code{timeSignatureFraction} determine where bar lines
-should be inserted, and how automatic beams should be
-generated.
-
-Changing the value of @code{timeSignatureFraction} also causes a
-fraction to be printed. This grob is @internalsref{TimeSignature}.
+command.
+@lilypond[fragment,verbatim]
+ \time 2/4 c'2 \time 3/4 c'2. 
+@end lilypond

 
 The actual symbol that's printed can be customized with the style
 property.
 
 The actual symbol that's printed can be customized with the style
 property.


@@ -744,12 +669,28 @@ property.
 \time 2/2 s2
 @end lilypond
 
 \time 2/2 s2
 @end lilypond
 

-There are many more options for the layout of this grob. They are
-selected through the @code{style} grob property.
+The grob for this symbol is @internalsref{TimeSignature}.  There are
+many more options for its layout. They are selected through the
+@code{style} grob property. See @file{input/test/time.ly} for more
+examples.

 
 

-@c FIXME: this isn't documented except in example?
-See
-@file{input/test/time.ly} for examples.
+
+The full syntax for this command is
+@example
+  \time @var{n}@code{/}@var{d} 
+@end example
+where @var{n} and @var{d} are integers. This command is internally
+translated, to the following:
+@example
+\property Score.timeSignatureFraction = #'(@var{n} . @var{d})
+\property Score.beatLength = #(make-moment 1 @var{d})
+\property Score.measureLength = #(make-moment @var{n} @var{d})
+@end example
+
+The property @code{timeSignatureFraction} determine where bar lines
+should be inserted, and how automatic beams should be generated.
+Changing the value of @code{timeSignatureFraction} also causes a
+fraction to be printed. 

 
 @c .   {Partial}
 @subsection Partial
 
 @c .   {Partial}
 @subsection Partial


@@ -762,20 +703,22 @@ See
 @cindex @code{\partial}
 
 Partial measures, for example in upbeats, are entered using the
 @cindex @code{\partial}
 
 Partial measures, for example in upbeats, are entered using the

-@code{\partial} command: 
+@code{\partial} command:
+@lilypond[fragment,verbatim]
+\partial 4* 5/16  c'16 c8. f16 a'2. ~ a'8. a'16 | g'1
+@end lilypond
+
+The syntax for this command is 

 @example
   \partial @var{duration} 
 @end example
 @example
   \partial @var{duration} 
 @end example

-
-Internally,  this is a shortcut for 
-
+This is  internally translated into

 @example
   \property Score.measurePosition = -@var{length of duration}
 @end example
 @cindex @code{|}
 @example
   \property Score.measurePosition = -@var{length of duration}
 @end example
 @cindex @code{|}

-

 The property @code{measurePosition} contains a rational number
 The property @code{measurePosition} contains a rational number

-indicating how much of the measure has passed at this point. 
+indicating how much of the measure has passed at this point.

 
 
 @node Unmetered music
 
 
 @node Unmetered music


@@ -807,16 +750,13 @@ shortcuts.
 @cindex measure lines
 @cindex repeat bars
 
 @cindex measure lines
 @cindex repeat bars
 

-@example
-  \bar @var{bartype}
-@end example
+Bar lines are inserted automatically by, but if you need a special
+types of barline, you can force one using the @code{\bar} command:
+@lilypond[fragment,verbatim]
+  c4 \bar "|:" c4
+@end lilypond

 
 

-This is a shortcut for doing
-@example
-  \property Score.whichBar = @var{bartype} 
-@end example

 The following bar types are available
 The following bar types are available

-

 @lilypond[fragment,  relative, singleline, verbatim]
 c4
 \bar "|" c
 @lilypond[fragment,  relative, singleline, verbatim]
 c4
 \bar "|" c


@@ -829,10 +769,33 @@ c4
 \bar "|." 
 @end lilypond
 
 \bar "|." 
 @end lilypond
 

-

 You are encouraged to use @code{\repeat} for repetitions.  See
 @ref{Repeats}.
 
 You are encouraged to use @code{\repeat} for repetitions.  See
 @ref{Repeats}.
 

+In scores with many staffs, the barlines are automatically placed at
+top level, and they are connected between different staffs of a
+@internalsref{StaffGroup}:
+@lilypond[fragment, verbatim]
+< \context StaffGroup <
+  \context Staff = up { e'4 d'
+     \bar "||"
+     f' e' }
+  \context Staff = down { \clef bass c4 g e g } >
+\context Staff = pedal { \clef bass c2 c2 } >
+@end lilypond
+
+The grobs that are created at @internalsref{Staff} level. The name is
+@internalsref{BarLine}.
+
+The full syntax for this command is  
+@example
+  \bar @var{bartype}
+@end example
+where @var{bartype} is a string. This is a shortcut for doing
+@example
+  \property Score.whichBar = @var{bartype} 
+@end example
+

 
 @cindex Bar_line_engraver
 @cindex whichBar
 
 @cindex Bar_line_engraver
 @cindex whichBar


@@ -848,8 +811,6 @@ a measure it is set to @code{defaultBarType}. The contents of
 @code{\bar  }.  These settings take precedence over the automatic
 @code{whichBar} settings. 
 
 @code{\bar  }.  These settings take precedence over the automatic
 @code{whichBar} settings. 
 

-@internalsref{BarLine} grobs are created by the @code{Bar_engraver}.
-

 @c .   {Polyphony}
 @node Polyphony
 @section Polyphony
 @c .   {Polyphony}
 @node Polyphony
 @section Polyphony


@@ -865,7 +826,7 @@ short-lived voices (make a chord of voices) or for single chords:
 
 @lilypond[verbatim,fragment]
 \context Voice = VA \apply #voicify-music \relative c'' {
 
 @lilypond[verbatim,fragment]
 \context Voice = VA \apply #voicify-music \relative c'' {

- c4 < { f d e  } \\ { b c2 } > c4 < g' \\ c, \\  f \\ d >
+ c4 < { f d e  } \\ { b c2 } > c4 < g' \\ b, \\  f \\ d >

 }
 @end lilypond
 
 }
 @end lilypond
 


@@ -873,20 +834,23 @@ 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
 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.
+context for each part, and use @code{\voiceOne}, up to
+@code{\voiceFour} to assign a stem directions and horizontal shift for
+each part.

 @c
 @c

-@lilypond[fragment,verbatim]
-\context Staff
-< \context Voice = VA { \stemUp b'4 a' g' f' e' }
-  \context Voice = VB { \stemDown g'4 g' g' g' g' } >
+
+@lilypond[singleline, verbatim]
+\relative c''
+\context Staff < \context Voice = VA { \voiceOne cis2 b  }
+  \context Voice = VB { \voiceThree b4 ais ~ ais4 gis4 } 
+  \context Voice = VC { \voiceTwo fis4~  fis4 f ~ f  } >

 @end lilypond
 
 @end lilypond
 

-When there are more than two voices on a staff, you must also indicate
-which voice should moved horizontally in case of a collision. This can
-be done with the identifiers @code{\shiftOff}, @code{\shiftOn},
-@code{\shiftOnn}, etc. (which sets the grob property @code{horizontal-shift}
-in @internalsref{NoteColumn}).
+The identifiers @code{\voiceOne} to @code{\voiceFour} set directions
+ties, slurs and stems, and set shift directions.

 
 

+If you want more than four voices, you can also manually set
+horizontal shifts and stem directions, as is shown  in the following example:

 @lilypond[fragment, verbatim]
   \context Staff \notes\relative c''<
        \context Voice=one {
 @lilypond[fragment, verbatim]
   \context Staff \notes\relative c''<
        \context Voice=one {


@@ -904,72 +868,180 @@ in @internalsref{NoteColumn}).
   >
 @end lilypond
 
   >
 @end lilypond
 

-The most convenient way is to use the identifiers @code{\voiceOne}
-through @code{\voiceFour}, which also set slur and tie directions in the
-correct manner.
-
-@lilypond[singleline, verbatim]
-\relative c''
-\context Staff < \context Voice = VA { \voiceOne cis2 b  }
-  \context Voice = VB { \voiceThree b4 ais ~ ais4 gis4 } 
-  \context Voice = VC { \voiceTwo fis4~  fis4 f ~ f  } >
-@end lilypond

 
 Normally, note heads with a different number of dots are not merged, but
 if you set the grob property @code{merge-differently-dotted}, they are:
 
 Normally, note heads with a different number of dots are not merged, but
 if you set the grob property @code{merge-differently-dotted}, they are:

-

 @lilypond[verbatim,fragment,singleline]
 @lilypond[verbatim,fragment,singleline]

-  \context Staff <
-  \context Voice = VA { \voiceOne
+\apply #voicify-music < {

      g'8 g'8 
      \property Staff.NoteCollision \override #'merge-differently-dotted = ##t
      g'8 g'8
      g'8 g'8 
      \property Staff.NoteCollision \override #'merge-differently-dotted = ##t
      g'8 g'8

-  }
-  \context Voice = VB { \voiceTwo [g'8. f16] [g'8. f'16] } 
+  } \\ { [g'8. f16] [g'8. f'16] } 

   >
 @end lilypond
 
   >
 @end lilypond
 

+Similarly, you can merge half note heads with eighth notes, by setting
+@code{merge-differently-headed}:
+@lilypond[fragment, relative=2,verbatim]
+\apply #voicify-music < {
+    c8 c4.
+    \property Staff.NoteCollision
+      \override #'merge-differently-headed = ##t
+    c8 c4. } \\ { c2 c2 } >
+@end lilypond
+

 LilyPond also vertically shifts rests that are opposite of a stem. 
 
 LilyPond also vertically shifts rests that are opposite of a stem. 
 

-@lilypond[singleline,verbatim]
-\context Staff <
-\context Voice {  \stemUp c''4  }
-\context Voice =VB { r4 }
+@lilypond[singleline,fragment,verbatim]
+\apply #voicify-music <
+ { c''4  } \\  { r4 }

 >
 @end lilypond
 
 >
 @end lilypond
 

-Note head collisions (horizontal shifting of note heads) are handled by
-the @internalsref{NoteCollision} grob. @internalsref{RestCollision}
-handles vertical shifting of rests.
+Note head collisions (horizontal shifting of note heads) are handled by
+the @internalsref{NoteCollision} grob. @internalsref{RestCollision}
+handles vertical shifting of rests.
+
+
+
+@refbugs
+
+Resolving collisions is a very intricate subject, and LilyPond only
+handles a few situations. When it can not cope, you are advised to use
+@code{force-hshift} of the @internalsref{NoteColumn} grob and pitched
+rests to override typesetting decisions.
+
+@node Beaming
+@section Beaming
+
+Beams are used to group short notes into chunks that are aligned with
+the metrum. They are inserted automatically in most cases.
+
+@lilypond[fragment,verbatim, relative=2]
+\time 2/4 c8 c c c \time 6/8 c c c c8. c16  c8
+@end lilypond
+
+If you're not satisfied with the automatic beaming, you can enter the
+beams explicitly. If you have beaming patterns that differ from the
+defaults, you can also set the patterns for automatic beamer.
+
+The beam symbol is @internalsref{Beam} in @internalsref{Voice}
+context, both for automatically created and manual beams.
+
+@c .    {Manual beams}
+@cindex Automatic beams
+@subsection Manual beams
+@cindex beams, manual
+@cindex @code{]}
+@cindex @code{[}
+
+In some cases it may be necessary to override LilyPond's automatic
+beaming algorithm.  For example, the auto beamer will not beam over
+rests or bar lines, If you want that, specify the begin and end point
+manually using a @code{[} before the first beamed note and a @code{]}
+after the last note:
+
+@lilypond[fragment,relative,verbatim]
+  \context Staff {
+    r4 [r8 g' a r8] r8 [g | a] r8
+  }
+@end lilypond
+
+@cindex @code{stemLeftBeamCount}
+
+Normally, beaming patterns within a beam are determined automatically.
+When this mechanism fouls up, the properties
+@code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount} can
+be used to control the beam subdivision on a stem.  If you set either
+property, it's value will be used only once, and then it is erased.
+
+@lilypond[fragment,relative,verbatim]
+  \context Staff {
+    [f8 r16 f g a]
+    [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a]
+  }
+@end lilypond
+@cindex @code{stemRightBeamCount}
+
+@ignore
+TODO: FIXME, we don't want this doc here.
+
+ can be tweaked through
+grob-property @code{positions}. The value is a pair.
+specify vertical location of the left and right end point. Both are
+measured in half staff-spaces, and the middle staff line is the value
+of 0.
+
+@li lypond[fragment,relative,verbatim]
+  \property Voice.Beam \set #'position = #
+  \property Voice.Beam \set #'height = #0
+  [a'8 e' d c]
+@end lilyp ond
+
+Here's how you'd specify a weird looking beam that instead of being
+horizontal, falls two staff spaces:
+
+
+[FIXME]
+
+
+@li lypond[fragment,relative,verbatim]
+  \property Voice.Beam \set #'staff-position = #4
+  \property Voice.Beam \set #'height = #-4
+  [c8 c] 
+@end lilypond
+
+@end ignore
+

 
 

+Kneed beams are inserted automatically, when a large gap between two
+adjacent beamed notes is detected. This behavior can be tuned through
+the grob property @code{auto-knee-gap}.

 
 

+@cindex beams, kneed
+@cindex kneed beams
+@cindex auto-knee-gap
+@cindex hara kiri

 
 
 
 

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

 
 @refbugs
 
 
 @refbugs
 

-Resolving collisions is a very intricate subject, and LilyPond only
-handles a few situations. When it can not cope, you are advised to use
-@code{force-hshift} of the NoteColumn grob and @code{staff-position} of
-the Rest grob to override typesetting decisions.
+Auto knee beams can not be used together with hara kiri staffs.

 
 

-@node Beaming
-@section Beaming
+@menu
+* Beam typography::             
+* Setting automatic beam behavior ::  
+@end menu

 
 

-Beams are used to group short notes into chunks that are aligned with
-the metrum.  LilyPond guesses where beams should be inserted. If you're
-not satisfied with the automatic beaming, you can specify which patterns
-to beam automatically. In specific cases, you can also enter the beams
-explicitly.
+@node Beam typography
+@subsection Beam typography
+
+One of the strong points of LilyPond is how beams are formatted. Beams
+are quantized, meaning that the left and right endpoints beams start
+exactly on staff lines. Without quantization, small wedges of white
+space appear between the beam and staff line, and this looks untidy.
+
+Beams are also slope-damped: melodies that go up or down should also
+have beams that go up or down, but the slope of the beams should be
+less than the slope of the notes themselves.
+
+Some beams should be horizontal. These are so-called concave beams. 
+
+[TODO: some pictures.]

 
 
 @c .    {Automatic beams}
 
 
 @c .    {Automatic beams}

-@subsection Automatic beams
+@node Setting automatic beam behavior 
+@subsection Setting automatic beam behavior 

 
 

-@cindex @code{Voice.autoBeamSettings}
+@cindex @code{autoBeamSettings}

 @cindex @code{(end * * * *)}
 @cindex @code{(begin * * * *)}
 @cindex @code{(end * * * *)}
 @cindex @code{(begin * * * *)}

-
+@cindex automatic beams, tuning
+@cindex tuning automatic beaming

 
 In normal time signatures, automatic beams can start on any note but can
 only end in a few positions within the measure: beams can end on a beat,
 
 In normal time signatures, automatic beams can start on any note but can
 only end in a few positions within the measure: beams can end on a beat,


@@ -1032,11 +1104,13 @@ accepting notes, this last beam will not be typeset at all.
 
 @cindex automatic beam generation
 @cindex autobeam
 
 @cindex automatic beam generation
 @cindex autobeam

-@cindex @code{Voice.noAutoBeaming}
+@cindex @code{Voice.autoBeaming}
+@cindex lyrics
+
+For melodies that have lyrics, you may want to switch off 
+automatic beaming. This is done by setting @code{Voice.autoBeaming} to
+@code{#f}. 

 
 

-Automatic beaming is on by default, but can be switched off by setting
-@code{Voice.noAutoBeaming} to true.  You you may find this necessary for
-a melody that goes with lyrics.

 
 @refbugs
 
 
 @refbugs
 


@@ -1053,86 +1127,17 @@ It is not possible to specify beaming parameters that act differently in
 different parts of a measure. This means that it is not possible to use
 automatic beaming in irregular meters such as @code{5/8}.
 
 different parts of a measure. This means that it is not possible to use
 automatic beaming in irregular meters such as @code{5/8}.
 

-@c .    {Manual beams}
-@cindex Automatic beams
-@subsection Manual beams
-@cindex beams, manual
-@cindex @code{]}
-@cindex @code{[}
-
-In some cases it may be necessary to override LilyPond's automatic
-beaming algorithm.  For example, the auto beamer will not beam over
-rests or bar lines, If you want that, specify the begin and end point
-manually using a @code{[} before the first beamed note and a @code{]}
-after the last note:
-
-@lilypond[fragment,relative,verbatim]
-  \context Staff {
-    r4 [r8 g' a r8] r8 [g | a] r8
-  }
-@end lilypond
-Whenever an manual beam is busy, the automatic beamer will not produce
-anything.
-
-@cindex @code{stemLeftBeamCount}
-
-Normally, beaming patterns within a beam are determined automatically.
-When this mechanism fouls up, the properties
-@code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount}.  can
-be used to control the beam subdivision on a stem.  If you set either
-property, it's value will be used only once, and then it is erased.
-
-@lilypond[fragment,relative,verbatim]
-  \context Staff {
-    [f8 r16 f g a]
-    [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a]
-  }
-@end lilypond
-@cindex @code{stemRightBeamCount}
-
-The beam symbol (grob @internalsref{Beam} in @internalsref{Voice}
-context), both for automatic and manual beams) can be tweaked through
-grob-properties @code{height} and @code{staff-position}. These specify
-vertical location and vertical span. Both are measured in half
-staff-spaces, @code{staff-position=0} corresponds to the middle staff
-line.
-
-Set @code{height} to zero, to get horizontal beams:
-
-@lilypond[fragment,relative,verbatim]
-  \property Voice.Beam \set #'direction = #1
-  \property Voice.Beam \set #'height = #0
-  [a'8 e' d c]
-@end lilypond
-
-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}

 
 @node Expressive marks
 @section Expressive marks
 
 @c .   {Slurs}
 @menu
 
 @node Expressive marks
 @section Expressive marks
 
 @c .   {Slurs}
 @menu

-* Slurs ::                     
-* Phrasing slurs::             
-* Breath marks::               
-* Tempo::                      
-* Text spanners::              
+* Slurs ::                      
+* Phrasing slurs::              
+* Breath marks::                
+* Tempo::                       
+* Text spanners::               

 @end menu
 
 @node Slurs 
 @end menu
 
 @node Slurs 


@@ -1155,7 +1160,7 @@ grob-property @code{attachment} of @internalsref{Slur} in
 the attachment type of the left and right end points.
 
 @lilypond[fragment,relative,verbatim]
 the attachment type of the left and right end points.
 
 @lilypond[fragment,relative,verbatim]

-  \property Voice.Slur \set #'direction = #1
+  \slurUp

   \property Voice.Stem \set #'length = #5.5
   g'8(g)g4
   \property Voice.Slur \set #'attachment = #'(stem . stem)
   \property Voice.Stem \set #'length = #5.5
   g'8(g)g4
   \property Voice.Slur \set #'attachment = #'(stem . stem)


@@ -1167,8 +1172,7 @@ away upward or downward. If this happens, attaching the slur to the
 stems might look better:
 
 @lilypond[fragment,relative,verbatim]
 stems might look better:
 
 @lilypond[fragment,relative,verbatim]

-  \property Voice.Stem \set #'direction = #1
-  \property Voice.Slur \set #'direction = #1
+  \stemUp \slurUp

   d32( d'4 )d8..
   \property Voice.Slur \set #'attachment = #'(stem . stem)
   d,32( d'4 )d8..
   d32( d'4 )d8..
   \property Voice.Slur \set #'attachment = #'(stem . stem)
   d,32( d'4 )d8..


@@ -1185,8 +1189,7 @@ curved slur when LilyPond decides for a vertically moved one.  You can
 indicate this preference by increasing the @code{beautiful} value:
 
 @lilypond[verbatim,singleline,relative]
 indicate this preference by increasing the @code{beautiful} value:
 
 @lilypond[verbatim,singleline,relative]

-  \property Voice.Beam \override #'direction = #-1
-  \property Voice.Slur \override #'direction = #1
+  \stemDown \slurUp

   c16( a' f' a a f a, )c,
   c( a' f' a a f d, )c
   \property Voice.Slur \override #'beautiful = #5.0
   c16( a' f' a a f a, )c,
   c( a' f' a a f d, )c
   \property Voice.Slur \override #'beautiful = #5.0


@@ -1195,8 +1198,11 @@ indicate this preference by increasing the @code{beautiful} value:
 
 @refbugs
 
 
 @refbugs
 

-@code{beautiful} is an arbitrary parameter in the slur formatter.
-Useful values can only be determined by trial and error.
+Producing nice slurs is a difficult problem, and LilyPond currently
+uses a simple, empiric method to produce slurs. In some cases, the
+results of this method don't look too good.  This is reflected by the
+@code{beautiful} parameter. It is an arbitrary parameter in the slur
+formatter.  Useful values can only be determined by trial and error.

 
 @cindex Adjusting slurs
 
 
 @cindex Adjusting slurs
 


@@ -1229,16 +1235,6 @@ c'4 \breathe d4
 @end lilypond
 
 
 @end lilypond
 
 

-
-
-@refbugs
-
-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}
 @node Tempo
 @subsection Tempo
 @c .  {Tempo}
 @node Tempo
 @subsection Tempo


@@ -1296,11 +1292,12 @@ An application---or rather, a hack---is to fake octavation indications.
 @section Ornaments
 @cindex Ornaments
 @menu
 @section Ornaments
 @cindex Ornaments
 @menu

-* Articulations::              
-* Text scripts::               
-* Grace notes::                        
-* Glissando ::                 
-* Dynamics::                   
+* Articulations::               
+* Text scripts::                
+* Adding scripts::              
+* Grace notes::                 
+* Glissando ::                  
+* Dynamics::                    

 @end menu
 
 @c .   {Articulation}
 @end menu
 
 @c .   {Articulation}


@@ -1313,14 +1310,34 @@ An application---or rather, a hack---is to fake octavation indications.
 @cindex ornaments
 
 A variety of symbols can appear above and below notes to indicate
 @cindex ornaments
 
 A variety of symbols can appear above and below notes to indicate

-different characteristics of the performance.  These symbols can be
-added to a note with `@var{note}@code{-\}@var{name}'.  Numerous symbols
-are defined in @file{script.ly}.  Symbols can be forced to appear above
-or below the note by writing `@var{note}@code{^\}@var{name}' and
-`@var{note}@code{_\}@var{name}' respectively.  Here is a chart showing
-symbols on notes, with the name of the corresponding symbol appearing
-underneath.
+different characteristics of the performance. They are added to a note
+by adding @code{-}@var{script}
+@lilypond[singleline]
+  \score {
+    \notes \context Voice {
+      \property Voice.TextScript \set #'font-family = #'typewriter
+      \property Voice.TextScript \set #'font-shape = #'upright
+      c''4-._"c-."      s4
+      c''4--_"c-{}-"    s4
+      c''4-+_"c-+"      s4
+      c''4-|_"c-|"      s4
+      c''4->_"c->"      s4
+      c''4-^_"c-\\^{ }" s4
+    }
+  }
+@end lilypond

 
 

+The script is automatically placed, but if you need to force
+directions, you can use @code{_} to force them down, or @code{^} to
+put them up:
+@lilypond[fragment, verbatim]
+  c''4^^ c''4_^
+@end lilypond
+
+
+Other symbols can be added using the syntax
+@var{note}@code{-\}@var{name}. Again, they can be forced up or down
+using @code{^} and @code{_}.

 @lilypond[]
   \score {
     <
 @lilypond[]
   \score {
     <


@@ -1354,26 +1371,12 @@ underneath.
   }
 @end lilypond
 
   }
 @end lilypond
 

-To save typing work, some shorthands are available:
-@lilypond[singleline]
-  \score {
-    \notes \context Voice {
-      \property Voice.TextScript \set #'font-family = #'typewriter
-      \property Voice.TextScript \set #'font-shape = #'upright
-      c''4-._"c-."      s4
-      c''4--_"c-{}-"    s4
-      c''4-+_"c-+"      s4
-      c''4-|_"c-|"      s4
-      c''4->_"c->"      s4
-      c''4-^_"c-\\^{ }" s4
-    }
-  }
-@end lilypond

 
 @cindex fingering
 
 
 @cindex fingering
 

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

 @lilypond[verbatim, singleline, fragment]
       c'4-1 c'4-2 c'4-3 c'4-4
       c^#'(finger "2-3")
 @lilypond[verbatim, singleline, fragment]
       c'4-1 c'4-2 c'4-3 c'4-4
       c^#'(finger "2-3")


@@ -1385,17 +1388,6 @@ changes, some markup texts would be needed:
 @cindex superscript
 @cindex subscript
 
 @cindex superscript
 @cindex subscript
 

-You can add scripts by editing @file{scm/script.scm}. This file contains
-a table, listing script definitions and aliases. The following syntax
-accesses a script definition from the table:
-
-@example
-  \script @var{alias}
-@end example
-
-Usually the @code{\script} keyword is not used directly.  Various
-helpful identifier definitions appear in @file{script.ly}.
-

 Grobs for these objects are @internalsref{Script} and @internalsref{Fingering}.
 
 @refbugs
 Grobs for these objects are @internalsref{Script} and @internalsref{Fingering}.
 
 @refbugs


@@ -1418,26 +1410,41 @@ text (see @ref{Text markup}) above or below notes by using a string:
 @code{c^"text"}. 
 
 By default, these indications do not influence the note spacing, but
 @code{c^"text"}. 
 
 By default, these indications do not influence the note spacing, but

-if @code{Voice.textNonEmpty} is set to true the widths will be taken
-into account.  The identifier @code{\fatText} is defined in the standard
-includes.
-@lilypond[fragment,singleline,verbatim]
-\relative c' { c4^"longtext" \fatText c4_"longlongtext" c4 }
+by using the command @code{\fatText}, the widths will be taken into
+account.
+@c
+@lilypond[fragment,singleline,verbatim] \relative c' {
+c4^"longtext" \fatText c4_"longlongtext" c4 }

 @end lilypond
 
 Text scripts are created in form of @internalsref{TextScript} grobs, in
 @end lilypond
 
 Text scripts are created in form of @internalsref{TextScript} grobs, in

-@internalsref{Voice} context.
+@internalsref{Voice} context. 

 
 @ref{Text markup} describes how to change the font or access
 special symbols in text scripts.
 
 
 @ref{Text markup} describes how to change the font or access
 special symbols in text scripts.
 

-@c .   {Grace notes}
-@node Grace notes
-@subsection Grace notes

 
 

+@node Adding scripts
+@subsection  Adding scripts
+
+TODO: should junk this subsect?
+
+You can add scripts by editing @file{scm/script.scm} and
+@file{ly/script-init.ly}. This file contains a table, listing script
+definitions and aliases. The following syntax accesses a script
+definition from the table:
+
+@example
+  \script @var{alias}
+@end example

 
 

+Usually the @code{\script} keyword is not used directly.  Various
+helpful identifier definitions appear in @file{script.ly}.

 
 
 
 

+@c .   {Grace notes}
+@node Grace notes
+@subsection Grace notes

 
 
 
 
 
 


@@ -1447,6 +1454,7 @@ special symbols in text scripts.
 @cindex grace notes
 @cindex @code{graceAlignPosition}
 
 @cindex grace notes
 @cindex @code{graceAlignPosition}
 

+

 Grace notes are ornaments that are written out, but do not take up  any
 logical time in a measure. LilyPond has limited support for grace notes.
 The syntax is as follows. 
 Grace notes are ornaments that are written out, but do not take up  any
 logical time in a measure. LilyPond has limited support for grace notes.
 The syntax is as follows. 


@@ -1637,11 +1645,12 @@ Make beat or measure repeats. These look like percent signs.
 @end table  
 
 @menu
 @end table  
 
 @menu

-* Repeat syntax::              
-* Manual repeat commands::     
-* Tremolo repeats::            
-* Tremolo subdivisions::       
-* Measure repeats::            
+* Repeat syntax::               
+* Repeats and MIDI::            
+* Manual repeat commands::      
+* Tremolo repeats::             
+* Tremolo subdivisions::        
+* Measure repeats::             

 @end menu
 
 @node Repeat syntax
 @end menu
 
 @node Repeat syntax


@@ -1700,7 +1709,7 @@ the specified number of repeats.
 }
 @end lilypond
 
 }
 @end lilypond
 

-@subsection Repeats and MIDI
+@node Repeats and MIDI

 @subsection Repeats and MIDI
 
 @cindex expanding repeats
 @subsection Repeats and MIDI
 
 @cindex expanding repeats


@@ -1839,7 +1848,7 @@ with slashes, and repeating that measure with percents.
 
 
 @menu
 
 
 @menu

-* Rhythmic staves::            
+* Rhythmic staves::             

 @end menu
 
 @node Rhythmic staves
 @end menu
 
 @node Rhythmic staves


@@ -1869,11 +1878,11 @@ behavior.  In this section we discuss the @internalsref{PianoStaff} and some
 other pianistic peculiarities.
 
 @menu
 other pianistic peculiarities.
 
 @menu

-* Automatic staff changes::    
-* Manual staff switches::      
-* Pedals::                     
-* Arpeggio::                   
-* Voice follower lines::       
+* Automatic staff changes::     
+* Manual staff switches::       
+* Pedals::                      
+* Arpeggio::                    
+* Voice follower lines::        

 @end menu 
 
 
 @end menu 
 
 


@@ -1886,13 +1895,15 @@ Voices can switch automatically between the top and the bottom
 staff. The syntax for this is
 @example
         \autochange @var{contexttype} \context @var{childcontexttype}
 staff. The syntax for this is
 @example
         \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}, 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.
+               @var{musicexp} 
+@end example
+@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 <


@@ -2090,15 +2101,107 @@ can be printed automatically. This is enabled if the property
 The associated grob is @internalsref{VoiceFollower}.
 
 
 The associated grob is @internalsref{VoiceFollower}.
 
 

+@node Tablatures
+@section Tablatures
+
+@menu
+* Tablatures basic::
+* Non-guitar tablatures::
+* Tablature in addition to normal staff::
+@end menu
+
+@node Tablatures basic
+@subsection Tablatures basic
+@cindex Tablatures basic
+
+Tablature can be typeset with Lilypond by using the
+@internalsref{TabStaff} and @internalsref{TabVoice} contexts. As
+tablatures is a recent feature in Lilypond, most of the guitar special
+effects (hammer, pull, bend, ...) are not yet supported.
+
+With the @internalsref{TabStaff}, the string number associated to a note
+is given though the fingering mechanism, e.g. @code{c4-3} for a C
+quarter on the third string. The string 1 is the lowest one, and the
+tuning defaults to the standard guitar tuning (with 6 strings).
+
+@lilypond[fragment,verbatim]
+  \context TabStaff <
+    \notes {
+      \property Staff.Stem \override #'direction = #1
+      
+      a,4-2 c'-5 a-4 e'-6
+      e-3 c'-5 a-4 e'-6
+    }
+  >  
+@end lilypond
+
+
+@node Non-guitar tablatures
+@subsection Non-guitar tablatures
+@cindex Non-guitar tablatures
+
+There are many ways to customize Lilypond tablatures.
+
+First you can change the number of string, e.g.
+@code{StaffSymbol \override #'line-count  = #5} to have only 5 strings.
+Because of a kind of bug in Lilypond, you MUST create a new type of
+context if you want different tablatures with diiferent number of
+strings.
+
+Then you can change the strings tuning. String tuning is given as a
+Scheme list with one integer number for each string, the number being
+the string note pitch if not fretted (open note).
+
+Finally, it is possible to change the Scheme function to format the
+tablature note text. The default is @var{fret-number-tablature-format},
+which uses the fret number, but for some instruments that may not use
+this notation, just create your own tablature-format function. This
+function takes three argument: the string number, the string tuning and
+the note pitch.
+
+
+@node Tablature in addition to normal staff
+@subsection Tablature in addition to normal staff
+@cindex Tablature in addition to normal staff
+
+It is possible to typeset both tablature and a "normal" staff, as
+commonly done in many parts.
+
+A common trick for that is to put the notes in a variables, and to hide
+the fingering information (which correspond to the string number) for
+the standard staff.
+
+@lilypond[fragment,verbatim]
+  part = \notes {
+    a,4-2 c'-5 a-4 e'-6
+    e-3 c'-5 a-4 e'-6
+  }
+  \context StaffGroup <
+    \context Staff <
+      % Hide fingering number (used for string number) for the "normal" staff
+      \property Staff.Fingering \override #'transparent = ##t
+      
+      \part
+    >
+    \context TabStaff <
+      \property Staff.Stem \override #'direction = #1
+      
+      \part
+    >
+  >  
+@end lilypond
+
+
+

 @node Lyrics
 @section Lyrics
 
 
 @menu
 @node Lyrics
 @section Lyrics
 
 
 @menu

-* Lyrics mode::                        
-* Printing lyrics::            
+* Lyrics mode::                 
+* Printing lyrics::             

 * Automatic syllable durations::  
 * Automatic syllable durations::  

-* More stanzas::               
+* More stanzas::                

 @end menu
 
 @c .  {Lyrics mode}
 @end menu
 
 @c .  {Lyrics mode}


@@ -2323,8 +2426,8 @@ not attempt to be intelligent. If you enter @code{f bes d}, it does not
 interpret this as an inversion.
 
 @menu
 interpret this as an inversion.
 
 @menu

-* Chords mode::                        
-* Printing named chords::      
+* Chords mode::                 
+* Printing named chords::       

 @end menu
 
 @c .  {Chords mode}
 @end menu
 
 @c .  {Chords mode}


@@ -2545,14 +2648,14 @@ problems in orchestral music.
 
 @c .  {Transpose}
 @menu
 
 @c .  {Transpose}
 @menu

-* Rehearsal marks::            
-* Bar numbers::                        
-* Instrument names::           
-* Transpose::                  
+* Rehearsal marks::             
+* Bar numbers::                 
+* Instrument names::            
+* Transpose::                   

 * Sound output for transposing instruments::  
 * Sound output for transposing instruments::  

-* Multi measure rests::                
-* Automatic part combining::   
-* Hara kiri staves::           
+* Multi measure rests::         
+* Automatic part combining::    
+* Hara kiri staves::            

 @end menu
 
 @c .   {Rehearsal marks}
 @end menu
 
 @c .   {Rehearsal marks}


@@ -2850,8 +2953,33 @@ example disappears in the second line.
 
 
 @c . {Custodes}
 
 
 @c . {Custodes}

+@node Ancient notation 
+@section Ancient notation
+
+@menu
+* Ancient note heads::          
+* Custodes::                    
+@end menu
+
+
+@node Ancient note heads
+@subsection Ancient note heads
+
+ To get a longa note head, you have to use mensural note heads. This
+is accomplished by setting the @code{style} property of the
+NoteHead grob to @code{mensural}. There is also a note head style
+@code{baroque} which gives mensural note heads for @code{\longa} and
+@code{\breve} but standard note heads for shorter notes.
+
+@lilypond[fragment,singleline,verbatim]
+ \property Voice.NoteHead \set #'style = #'mensural
+ \property Voice.NoteHead \set #'font-family = #'ancient
+ a'\longa
+@end lilypond
+

 @node Custodes
 @node Custodes

-@section Custodes
+@subsection Custodes
+

 @cindex Custos
 @cindex Custodes
 
 @cindex Custos
 @cindex Custodes
 


@@ -2908,6 +3036,60 @@ block:
 @}
 @end example
 
 @}
 @end example
 

+@node Ancient clefs 
+@section Ancient clefs
+
+LilyPond supports a variety of clefs, many of them ancient. These can
+be selected from the @code{ancient} font family, by setting
+@code{Staff.clefGlyph}) to the following values
+
+@table @code
+@item clefs-C
+ modern style C clef
+@item clefs-F
+ modern style F clef
+@item clefs-G
+ modern style G clef
+@item clefs-vaticana_do
+ Editio Vaticana style do clef
+@item clefs-vaticana_fa
+ Editio Vaticana style fa clef
+@item clefs-medicaea_do
+ Editio Medicaea style do clef
+@item clefs-medicaea_fa
+ Editio Medicaea style fa clef
+@item clefs-mensural1_c
+ modern style mensural C clef
+@item clefs-mensural2_c
+ historic style small mensural C clef
+@item clefs-mensural3_c
+ historic style big mensural C clef
+@item clefs-mensural1_f
+ historic style traditional mensural F clef
+@item clefs-mensural2_f
+ historic style new mensural F clef
+@item clefs-mensural_g
+ historic style mensural G clef
+@item clefs-hufnagel_do
+ historic style hufnagel do clef
+@item clefs-hufnagel_fa
+ historic style hufnagel fa clef
+@item clefs-hufnagel_do_fa
+ historic style hufnagel combined do/fa clef
+@item clefs-percussion
+ modern style percussion clef
+@end table
+
+@emph{Modern style} means ``as is typeset in current editions.''
+@emph{Historic style} means ``as was typeset or written in contemporary
+historic editions''.  @emph{Editio XXX style} means ``as is/was printed in
+Editio XXX.''
+
+@cindex Vaticana, Editio
+@cindex Medicaea, Editio
+@cindex hufnagel clefs
+
+

 
 @c . {Figured bass}
 @node Figured bass
 
 @c . {Figured bass}
 @node Figured bass


@@ -2938,13 +3120,13 @@ affecting a whole set of objects.  Second, you can select one specific
 object, and set a grob property in that object.
 
 @menu
 object, and set a grob property in that object.
 
 @menu

-* Tuning groups of grobs ::    
-* Tuning per grob ::           
-* What to tune?::              
-* Font selection::             
-* Text markup::                        
-* Invisible grobs::            
-* Dirty tricks::               
+* Tuning groups of grobs ::     
+* Tuning per grob ::            
+* What to tune?::               
+* Font selection::              
+* Text markup::                 
+* Invisible grobs::             
+* Dirty tricks::                

 @end menu
 
 @node Tuning groups of grobs 
 @end menu
 
 @node Tuning groups of grobs 


@@ -3065,6 +3247,11 @@ The backend is not very strict in type-checking grob properties. If you
 @code{\revert} properties that are expected to be set by default,
 LilyPond may crash.
 
 @code{\revert} properties that are expected to be set by default,
 LilyPond may crash.
 

+
+@cindex adjusting staff symbol
+@cindex StaffSymbol, using \property
+@cindex staff lines, setting number of
+

 Some grobs are created at the moment that their context is created. An
 example of such a grob is the staff itself (i.e. the horizontal lines).
 You can not change the appearance of the staff symbol by manipulating
 Some grobs are created at the moment that their context is created. An
 example of such a grob is the staff itself (i.e. the horizontal lines).
 You can not change the appearance of the staff symbol by manipulating


@@ -3490,13 +3677,13 @@ and (La)@TeX{} putting the notation on a page, including page breaks.
 The part of LilyPond is documented here.
 
 @menu
 The part of LilyPond is documented here.
 
 @menu

-* Paper block::                        
-* Paper variables::            
-* Font Size::                  
-* Paper size::                 
-* Line break::                 
-* Page break::                 
-* Output scaling::             
+* Paper block::                 
+* Paper variables::             
+* Font Size::                   
+* Paper size::                  
+* Line break::                  
+* Page break::                  
+* Output scaling::              

 @end menu
 
 @c .  {Paper block}
 @end menu
 
 @c .  {Paper block}


@@ -3746,10 +3933,10 @@ meaning that you don't have access to continuously scaled fonts.
 LilyPond can output processed music in different output formats.  
 
 @menu
 LilyPond can output processed music in different output formats.  
 
 @menu

-* TeX output::                 
-* PostScript output::          
-* Scheme output::              
-* ASCIIScript output::         
+* TeX output::                  
+* PostScript output::           
+* Scheme output::               
+* ASCIIScript output::          

 @end menu
 
 @node TeX output
 @end menu
 
 @node TeX output


@@ -3933,8 +4120,8 @@ It is currently not possible to use the percussion channel (generally
 channel 10 of a MIDI file).
 
 @menu
 channel 10 of a MIDI file).
 
 @menu

-* MIDI block::                 
-* MIDI instrument names::      
+* MIDI block::                  
+* MIDI instrument names::       

 @end menu
 
 @c .  {MIDI block}
 @end menu
 
 @c .  {MIDI block}


@@ -3960,7 +4147,7 @@ Assignments in the @code{\midi} block are not allowed.
 
 Context definitions follow precisely the same syntax as within the
 \paper block.  Translation modules for sound are called performers.
 
 Context definitions follow precisely the same syntax as within the
 \paper block.  Translation modules for sound are called performers.

-The contexts for MIDI output are defined in @file{ly/performer.ly}.
+The contexts for MIDI output are defined in @file{ly/performer-init.ly}.

 
 
 @node MIDI instrument names
 
 
 @node MIDI instrument names


@@ -3994,9 +4181,9 @@ number.
 @section Music entry
 @cindex Music entry
 @menu
 @section Music entry
 @cindex Music entry
 @menu

-* Relative::                   
-* Bar check::                  
-* Point and click::            
+* Relative::                    
+* Bar check::                   
+* Point and click::             

 @end menu
 
 When entering music with LilyPond, it is easy to introduce errors. This
 @end menu
 
 When entering music with LilyPond, it is easy to introduce errors. This


@@ -4214,12 +4401,12 @@ c d b bes a g c2 }
 @section Interpretation context
 
 @menu
 @section Interpretation context
 
 @menu

-* Creating contexts::          
-* Default contexts::           
-* Context properties::         
-* Engravers and performers::   
+* Creating contexts::           
+* Default contexts::            
+* Context properties::          
+* Engravers and performers::    

 * Changing context definitions::  
 * Changing context definitions::  

-* Defining new contexts::      
+* Defining new contexts::       

 @end menu
 
 
 @end menu
 
 


@@ -4248,9 +4435,8 @@ multiple voices at any point), a @internalsref{Staff} context is contained in
 Contexts associated with sheet music output are called @emph{notation
 contexts}, those for sound output are called @emph{performance
 contexts}. The default definitions of the standard notation and
 Contexts associated with sheet music output are called @emph{notation
 contexts}, those for sound output are called @emph{performance
 contexts}. The default definitions of the standard notation and

-performance contexts can be found in @file{ly/engraver.ly} and
-@file{ly/performer.ly}, respectively.
-
+performance contexts can be found in @file{ly/engraver-init.ly} and
+@file{ly/performer-init.ly}, respectively.

 
 @node Creating contexts
 @subsection Creating contexts
 
 @node Creating contexts
 @subsection Creating contexts


@@ -4448,7 +4634,7 @@ command will override any predefined settings.
 
  To simplify editing translators, all standard contexts have standard
 identifiers called @var{name}@code{Context}, e.g. @code{StaffContext},
 
  To simplify editing translators, all standard contexts have standard
 identifiers called @var{name}@code{Context}, e.g. @code{StaffContext},

-@code{VoiceContext}, see @file{ly/engraver.ly}.
+@code{VoiceContext}, see @file{ly/engraver-init.ly}.

 
 @node Defining new contexts
 @subsection Defining new contexts
 
 @node Defining new contexts
 @subsection Defining new contexts


@@ -4566,13 +4752,13 @@ such an identifier outside of @code{\score}, you must do
 This section describes details that were too boring to be put elsewhere.
 
 @menu
 This section describes details that were too boring to be put elsewhere.
 
 @menu

-* Top level::                  
-* Identifiers::                        
-* Music expressions::          
+* Top level::                   
+* Identifiers::                 
+* Music expressions::           

 * Manipulating music expressions::  
 * Manipulating music expressions::  

-* Assignments::                        
-* Lexical modes::              
-* Ambiguities::                        
+* Assignments::                 
+* Lexical modes::               
+* Ambiguities::                 

 @end menu
 
 @c .  {Top level}
 @end menu
 
 @c .  {Top level}


@@ -4811,7 +4997,7 @@ More examples are given in the distributed example files in
 
 @c .   {Span requests}
 @menu
 
 @c .   {Span requests}
 @menu

-* Span requests::              
+* Span requests::               

 @end menu
 
 @node Span requests
 @end menu
 
 @node Span requests


@@ -4970,15 +5156,15 @@ right time between
 Even more boring details, now on lexical side of the input parser.
 
 @menu
 Even more boring details, now on lexical side of the input parser.
 
 @menu

-* Comments::                   
-* Direct Scheme::              
-* Keywords::                   
-* Integers::                   
-* Reals::                      
-* Strings::                    
-* Main input::                 
-* File inclusion::             
-* Version information::                
+* Comments::                    
+* Direct Scheme::               
+* Keywords::                    
+* Integers::                    
+* Reals::                       
+* Strings::                     
+* Main input::                  
+* File inclusion::              
+* Version information::         

 @end menu
 
 
 @end menu