--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@setfilename mudela.info
+@settitle Reference Manual
+
+@node Top, , , (dir)
+@top
+@menu
+* Tutorial:: a tutorial introduction to lilypond
+* Reference Manual:: Reference Manual
+* Glossary:: A dictionary of musical terms.
+@end menu
+
+@macro keyindex {word}
+@cindex \word\
+
+@end macro
+
+@macro indexcode {word}
+@cindex \word\
+
+@end macro
+
+@node Tutorial, , , Top
+@menu
+* Introduction:: Introduction
+* The first tune:: The first tune
+* Lyrics and chords:: Lyrics and chords
+* Piano music:: Piano music
+* end of tutorial:: The end
+@end menu
+@chapter Tutorial
+
+@node Introduction, , , Tutorial
+@section Introduction
+
+
+LilyPond prints music from a specification that you, the user, supply.
+You have to give that specification using a @emph{language}. This
+document is a gentle introduction to that language, which is called
+Mudela, an acronym of Music Definition Language.
+
+This tutorial will demonstrate how to use Mudela by presenting
+examples of input along with resulting output. We will use English
+terms for notation. In case you are not familiar with those, you may
+consult the glossary that is distributed with LilyPond.
+
+The examples discussed are included in the distribution, in the
+subdirectory @file{input/tutorial/}. It is recommended that you
+experiment with writing Mudela input yourself, to get a feel for
+how LilyPond behaves.
+
+@node The first tune, , , Tutorial
+@section The first tune
+
+
+To demonstrate what LilyPond input looks like, we start off with a
+full fledged, yet simple example. It is a convoluted version
+of the famous menuet in J. S. Bach's @emph{Klavierbuechlein}.
+
+@mudela[verbatim]
+% lines preceded by a percent are comments.
+\include "paper16.ly"
+\score {
+ \notes
+ \relative c'' \sequential{
+ \time 3/4;
+ \key g;
+
+ \repeat "volta" 2 {
+ d4 g,8 a b c d4 g, g |
+ e'4 c8 d e fis g4 g, g |
+ c4 d8()c b a( )b4 c8 b a g |
+ a4 [b8 a] [g fis] g2. |
+ }
+
+ b'4 g8 a b g
+ a4 d,8 e fis d |
+ g4 e8 fis g d cis4 b8 cis a4 |
+ a8-. b-. cis-. d-. e-. fis-.
+ g4 fis e |
+ fis a, r8 cis8
+ d2.-\fermata
+ \bar "|.";
+ }
+ \paper {
+ % standard settings are too wide for a book
+ linewidth = 14.0 \cm;
+ }
+}
+@end mudela
+
+Enter it (or copy it, the filename is @file{menuet.ly}), compile it
+with LilyPond and view the output. Details of this procedure may vary
+from system to system. To create the output, one would issue the
+command `@code{ly2dvi menuet}'. @file{ly2dvi} is a program that does
+the job of running LilyPond and TeX, handling of titles and
+adjusting of page margins.
+
+If all goes well, the file @file{menuet.dvi} will be created.
+To view this output, issue the command `@code{xdvi menuet}'.
+
+Now that we are familiar with the procedure of producing output, we
+will analyse the input, line by line.
+@ignore
+Let's try to redo this
+@example
+
+ % lines preceded by a percent are comments.
+
+@end example
+The percent sign, `@code{%}', introduces a line comment. If you want to
+make larger comments, you can use block comments. These are delimited
+by `@code{%@{}' and `@code{%@}}'
+@end ignore
+@multitable @columnfractions .60 .39
+@item
+@noindent
+@c @example urg: no tt font
+@c @exdent % lines preceded by a percent are comments.
+@exdent @code{% lines preceded by a percent are comments.}
+@c @end example
+@tab
+The percent sign, `@code{%}', introduces a line comment. If you
+want to make larger comments, you can use block comments. These
+are delimited by `@code{%@{}' and `@code{%@}}'
+@end multitable
+@example
+
+ \input "paper16.ly"
+
+@end example
+By default, LilyPond will use definitions for a 20
+point@footnote{A point is the standard measure of length for
+printing. One point is 1/72.27 inch.} high staff. We want smaller
+output (16 point staff height), so we must import the settings for
+that size, which is done.@example
+
+ \score @{
+
+@end example
+ A mudela file combines music with directions for outputting that
+music. The music is combined with the output directions by putting
+them into a @code{\score} block.
+@example
+
+ \notes
+
+@end example
+ This makes LilyPond ready for accepting notes.
+@example
+
+ \relative c''
+
+@end example
+ As we will see, pitches are combinations of octave, note name and
+chromatic alteration. In this scheme, the octave is indicated by
+using raised quotes (`@code{'}') and ``lowered'' quotes (commas:
+`@code{,}'). The central C is denoted by @code{c'}. The C one octave
+higher is @code{c''}. One and two octaves below the central C is
+denoted by @code{c} and @code{c,} respectively.
+
+For pitches in a long piece you might have to type many quotes. To
+remedy this, LilyPond has a ``relative'' octave entry mode. In this
+mode, octaves of notes without quotes are chosen such that a note is
+as close as possible (graphically, on the staff) to the the preceding
+note. If you add a high-quote an extra octave is added. The lowered
+quote (a comma) will subtract an extra octave. Because the first note
+has no predecessor, you have to give the (absolute) pitch of the note
+to start with.@example
+
+ \sequential @{
+
+@end example
+ What follows is sequential music, i.e.,
+notes that are to be played and printed after each other.@example
+
+ \time 3/4;
+
+@end example
+ This command changes the time signature of the current piece: a 3/4
+sign is printed. This command is also used to generate bar lines in
+the right spots.@example
+
+ \key g;
+
+@end example
+ This command changes the current key to G-major. Although this
+command comes after the @code{\time} command, in the output, the key
+signature comes before the time signature: LilyPond knows about music
+typesetting conventions. @example
+
+ \repeat "volta" 2
+
+@end example
+ This command tells LilyPond that the following piece of music must
+be played twice; @code{"volta"} volta brackets should be used for
+alternatives---if there were any.
+@example
+
+ @{
+
+@end example
+The subject of the repeat is again sequential music. Since
+@code{\sequential} is such a common construct, a shorthand is provided:
+just leave off @code{\sequential}, and the result is the same. @example
+
+ d4
+
+@end example
+ This is a note with pitch @code{d} (determined up to octaves). The
+relative music was started with a @code{c''}, so the real pitch of this
+note is @code{d''}. The @code{4} designates the duration of the note
+(it is a quarter note). @example
+
+ a b
+
+@end example
+These are notes with pitch @code{a} and @code{b}. Because their
+duration is the same as the @code{g}, there is no need to enter the
+duration (You may enter it anyway, eg. @code{a4 b4}) @example
+
+ d4 g, g |
+
+@end example
+ Three more notes. The `@code{|}' character is a `barcheck'. When
+processing the music, LilyPond will verify that barchecks are found at
+the start of a measure. This can help you track down errors.
+
+ So far, no notes were chromatically altered. Here is the first one
+that is: @code{fis}. Mudela by default uses Dutch note names, and
+``Fis'' is the Dutch note name for ``F sharp''. However, there is no
+sharp sign in the output. The program keeps track of key signatures,
+and will only print accidentals if they are needed.
+@example
+
+ c8 d e fis
+
+@end example
+LilyPond guesses were beams can be added to eighth and shorter notes.
+In this case, a beam over 4 eighths is added.
+@example
+
+ c4 d8( )c b a( )b4 c8 b a g |
+
+@end example
+ The next line shows how to make a slur:
+the beginning and ending note of the slur is marked with an opening and
+closing parenthesis respectively. In the line shown above this is
+done for two slurs. Slur markers (parentheses) are between
+the notes.@example
+
+ a4 [b8 a] [g fis]
+
+@end example
+Automatic beaming can be overridden by inserting beam marks
+(brackets). Brackets are put around notes you want beamed.@example
+
+ g2. |
+
+@end example
+A duration with augmentation dot is notated
+with the duration number followed by a period.@example
+
+ @}
+
+@end example
+ This ends the sequential music to be repeated. LilyPond will typeset
+a repeat bar. @example
+
+ cis'4 b8 cis a4 |
+
+@end example
+ This line shows that Lily will print an accidental if that is
+needed: the first C sharp will be printed with an accidental, the
+second one without. @example
+
+ a8-. b-. cis-. d-. e-. fis-.
+
+@end example
+You can enter articulation signs either in a verbose form using a
+shorthand. Here we demonstrate the shorthand: it is formed by a dash
+and the the character for the articulation to use, e.g. `@code{-.}' for
+staccato as shown above. @example
+
+ fis a, r8 cis8
+
+@end example
+
+Rests are denoted by the special notename `@code{r}'. You can also enter
+an invisible rest by using the special notename `@code{s}'.
+@example
+
+ d2.-\fermata
+
+@end example
+ All articulations have a verbose form, like @code{\fermata}. The
+command `@code{\fermata}' is not part of the core of the language (most
+of the other discussed elements are), but it is a shorthand for a more
+complicated description of a fermata. @code{\fermata} names that
+description and is therefore called an @emph{identifier}. @example
+
+ @}
+
+@end example
+
+Here the music ends.
+@example
+
+ \paper @{
+ linewidth = 14.0\cm;
+ @}
+
+@end example
+This specifies a conversion from music to notation output. Most of
+the details of this conversions (font sizes, dimensions, etc.) have
+been taken care of, but to fit the output in this document, it has
+to be smaller. We do this by setting the line width to 14 centimeters
+(approximately 6 inches).
+@example
+
+ @}
+
+@end example
+The last brace ends the @code{\score} block.
+
+There are two things to note here. The format contains musical
+concepts like pitches and durations, instead of symbols and positions:
+the input format tries to capture the meaning of @emph{music}, and not
+notation. Therefore Second, the format tries to be @emph{context-free}:
+a note will sound the same regardless of the current time signature,
+the key, etc.
+
+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 esthetic decisions. All
+symbols and their placement is @emph{generated} from a high-level musical
+description. In other words, LilyPond would be best
+described by `music compiler' or `music to notation compiler'.
+
+@node Lyrics and chords, , , Tutorial
+@section Lyrics and chords
+
+In this section we show how to typeset a song of unknown
+origin.@footnote{The author would welcome information about the origin
+of this song.}.
+
+@example
+\header @{
+ title = "The river is flowing";
+ composer = "Traditional (?)";
+@}
+\include "paper16.ly"
+melody = \notes \relative c' @{
+ \partial 8;
+ g8 |
+ c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
+ c4 c8 d [es () d] c4 | d4 es8 d c4.
+ \bar "|.";
+@}
+
+text = \lyrics @{
+ The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
+ ri -- ver is flo -- wing down to the sea.
+@}
+
+accompaniment =\chords @{
+ r8
+ c2-3- f-3-.7 d-min es4 c8-min r8
+ c2-min f-min7 g-7^3.5 c-min @}
+
+\score @{
+ \simultaneous @{
+% \accompaniment
+ \context ChordNames \accompaniment
+
+ \addlyrics
+ \context Staff = mel @{
+ \property Staff.noAutoBeaming = "1"
+ \property Staff.automaticMelismata = "1"
+ \melody
+ @}
+ \context Lyrics \text
+ @}
+ \midi @{ @}
+ \paper @{ linewidth = 10.0\cm; @}
+@}
+@end example
+
+
+The result would look this@footnote{The titling and font size shown
+may differ, since the titling in this document is not generated by
+@file{ly2dvi}.}.
+
+@center @strong{The river is flowing}
+@center Traditional
+
+@mudela[center]
+\header {
+ title = "The river is flowing";
+ composer = "Traditional (?)";
+}
+\include "paper16.ly"
+melody = \notes \relative c' {
+ \partial 8;
+ g8 |
+ c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
+ c4 c8 d [es () d] c4 | d4 es8 d c4.
+ \bar "|.";
+}
+
+text = \lyrics {
+ The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
+ ri -- ver is flo -- wing down to the sea.
+}
+
+accompaniment =\chords {
+ r8
+ c2-3- f-3-.7 d-min es4 c8-min r8
+ c2-min f-min7 g-7^3.5 c-min }
+
+\score {
+ \simultaneous {
+% \accompaniment
+ \context ChordNames \accompaniment
+
+ \addlyrics
+ \context Staff = mel {
+ \property Staff.noAutoBeaming = "1"
+ \property Staff.automaticMelismata = "1"
+ \melody
+ }
+ \context Lyrics \text
+ }
+ \midi { }
+ \paper { linewidth = 10.0\cm; }
+}
+@end mudela
+
+Again, we will dissect the file line by line.@example
+
+ \header @{
+
+@end example
+Information about the music you are about to typeset goes into a
+@code{\header} block. The information in this block is not used by
+LilyPond, but it is included in the output. @file{ly2dvi} uses this
+information to print titles above the music.
+@example
+
+ title = "The river is flowing";
+ composer = "Traditional (?)";
+@end example
+the @code{\header} block contains assignments. An assignment starts
+with a string. (which is unquoted, in this case). Then comes the
+equal sign `@code{=}'. After the equal sign comes the expression you
+want to store. In this case, you want to put in strings. The
+information has to be quoted here, because it contains spaces. The
+assignment is finished with a semicolon.@example
+
+ \include "paper16.ly"
+
+@end example
+Smaller size for inclusion in a book.@example
+
+ melody = \notes \relative c' @{
+
+@end example
+The structure of the file will be the same as the previous one, a
+@code{\score} block with music in it. To keep things readable, we will
+give names to the different parts of music, and use the names to
+construct the music within the score block.
+
+@example
+
+ \partial 8;
+
+@end example
+
+The piece starts with an anacrusis of one eighth. @example
+
+ c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
+ c4 c8 d [es () d] c4 | d4 es8 d c4.
+ \bar "|.";
+
+@end example
+We use explicit beaming. Since this is a song, we will turn automatic
+beams off, and use explicit beaming where needed.@example
+
+ @}
+
+@end example
+This ends the definition of @code{melody}. Note that there are no
+semicolons after assignments at top level.@example
+
+ text = \lyrics @{
+
+@end example
+Another identifier assignment. This one is for the lyrics.
+Lyrics are formed by syllables that have duration, and not by
+notes. To make LilyPond parse words as syllables, switch it into
+lyrics mode with @code{\lyrics}. Again, the brace after @code{\lyrics}
+is a shorthand for @code{\sequential @{}. @example
+
+ The4 ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
+ ri- ver is flo- __ wing down to the sea.
+ @}
+
+@end example
+The syllables themselves are separated by spaces. You can get syllable
+extenders by entering `@code{__}', and centered hyphens with
+`@code{-}@code{-}'. We enter the syllables as if they are all quarter notes
+in length (hence the @code{4}), and use a feature to align the
+syllables to the music (which obviously isn't all quarter notes.)
+@example
+
+ accompaniment =\chords @{
+
+@end example
+We'll put chords over the music. There is a special mode (analogous
+to @code{\lyrics} and @code{\notes} mode) where you can give the names
+of the chords you want, instead of the notes comprising the chord.
+@example
+
+ r8
+
+@end example
+There is no accompaniment during the anacrusis.@example
+
+ c2-3- f-3-.7
+
+@end example
+A chord is started by the tonic of the chord. The
+first one lasts a half note. An unadorned note creates a major
+triad, while a minor triad is wanted. @code{3-} modifies the third to
+be small. @code{7} modifies (adds) a seventh, which is small by default
+to create the @code{f a c es} chord. Multiple modifiers must be
+separated by a dot.@example
+
+ d-min es4 c8-min r8
+
+@end example
+Some modifiers have predefined names, eg. @code{min} is the same as
+@code{3-}, so @code{d-min} is a minor @code{d} chord.@example
+
+ c2-min f-min7 g-7^3.5 c-min @}
+
+@end example
+A named modifier @code{min} and a normal modifier @code{7} do not have
+to be separated by a dot. Tones from a chord are removed with chord
+subtractions. Subtractions are started with a caret, and they are
+also separated by dots. In this example, @code{g-7^3.5} produces a
+minor seventh. The brace ends the sequential music. @example
+
+ \score @{
+ \simultaneous @{
+
+@end example
+We assemble the music in the @code{\score} block. Melody, lyrics and
+accompaniment have to sound at the same time, so they should be
+@code{\simultaneous}.@example
+
+ %\accompaniment
+
+@end example
+Chord mode generates notes grouped in @code{\simultaneous} music. If
+you remove the comment sign, you can see the chords in normal
+notation: they will be printed as note heads on a separate
+staff. @example
+
+ \context ChordNames \accompaniment
+
+@end example
+Normally, the notes that you enter are transformed into note heads.
+The note heads alone make no sense, they need surrounding information:
+a key signature, a clef, staff lines, etc. They need @emph{context}. In
+LilyPond, these symbols are created by objects called `interpretation
+context'. Interpretation contexts only exist during a run of
+LilyPond. Interpretation contexts that are for printing music (as
+opposed to playing music) are called `notation context'.
+
+By default, LilyPond will create a Staff contexts for you. If you
+would remove the @code{%} sign in the previous line, you can see that
+mechanism in action.
+
+We don't want default contexts here, because we want names, not note
+heads. An interpretation context can also created upon explicit
+request. The keyword for such a request is @code{\context}. It takes
+two arguments. The first is the name of a interpretation context.
+The name is a string, it can be quoted with double quotes). The
+second argument is the music that should be interpreted in this
+context. For the previous line, we could have written @code{\context
+Staff \accompaniment}, and get the same effect.@example
+
+ \addlyrics
+
+@end example
+The lyrics need to be aligned with the melody. This is done by
+combining both with @code{\addlyrics}. @code{\addlyrics} takes two
+pieces of music (usually a melody and lyrics, in that order) and
+aligns the syllables of the second piece under the notes of the
+first piece. If you would reverse the order, the notes would be
+aligned on the lyrics, which is not very useful. (Besides, it looks
+silly.)@example
+
+ \context Staff = mel @{
+
+@end example
+This is the argument of @code{\addlyrics}. We instantiate a
+@code{Staff} context explicitly: should you chose to remove comment
+before the ``note heads'' version of the accompaniment, the
+accompaniment will be on a nameless staff. The melody has to be on a
+different staff as the accompaniment. This is accomplished by giving
+the melody staff a different name.@example
+
+ \property Staff.noAutoBeaming = "1"
+
+@end example
+An interpretation context has variables that tune its behaviour. One
+of the variables is @code{noAutoBeaming}. If set and non-zero (i.e.,
+true) LilyPond will not try to put automatic beaming on the current
+staff.@example
+
+ \property Staff.automaticMelismata = "1"
+
+@end example
+Similarly, we don't want to print a syllable when there is
+a slur. This sets up the Staff context to signal slurs while
+@code{\addlyrics} is processed. @example
+
+ \melody
+ @}
+
+@end example
+Finally, we put the melody on the current staff. Note that the
+@code{\property} directives and @code{\melody} are grouped in sequential
+music, so the property settings are done before the melody is
+processed. @example
+
+ \context Lyrics \text
+
+@end example
+The second argument of @code{\addlyrics} is the text. The text also
+should not land on a Staff, but on a interpretation context for
+syllables, extenders, hyphens etc. This context is called
+Lyrics.@example
+
+ @}
+
+@end example
+This ends @code{\simultaneous}.@example
+
+ \midi @{ @}
+
+@end example
+This makes the music go to a MIDI file. MIDI is great for
+checking music you enter. You listen to the MIDI file: if you hear
+something unexpected, it's probably a typing error. @code{\midi} is an
+`output definition', a declaration that specifies how to output music
+analogous to @code{\paper @{ @}}.@example
+
+ \paper @{ linewidth = 10.0\cm; @}
+
+@end example
+We also want notation output. The linewidth is short so the piece
+will be set in two lines. @example
+
+ @}
+
+@end example
+End the score block.
+
+@node Piano music, , , Tutorial
+@section Piano music
+
+Our third subject is a piece piano music. The fragment in the input
+file is a piano reduction of the G major Sinfonia by Giovanni Battista
+Sammartini. It was composed around 1740.
+
+@mudela[verbatim]
+
+\include "paper16.ly";
+
+viola = \notes \relative c' \context Voice = viola {
+ <c4-\f g' c>
+ \property Voice.verticalDirection = \down g'8. b,16
+ s1 s2. r4
+ g
+}
+
+oboes = \notes \relative c'' \context Voice = oboe {
+ \stemup s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
+ \grace <e8( g> <d4 f> <c2 e> \times 2/3 { <d8 \< f> <e g> <f a> }
+ <
+ { \times 2/3 { a8 g c } \! c2 }
+ \context Voice = oboeTwo {
+ \stemdown
+ \grace {
+ \property Grace.verticalDirection = \down
+ [f,16 g] }
+ f8 e e2
+ } >
+ \stemboth
+ \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
+ [<d ( f> < )f8. a>] <)b,8 d> r [<d16( f> <f8. )a>] <b,8 d> r |
+ [<c16( e> < )e8. g>] <c8 e,>
+}
+
+hoomPah = \notes \transpose c' {
+ c8 \translator Staff = top \stemdown
+ c'8 \translator Staff = bottom \stemup }
+
+hoomPahHoomPah = { [\hoomPah \hoomPah] }
+
+bassvoices = \notes \relative c' {
+ c4 g8. b,16
+ \hoomPahHoomPah \hoomPahHoomPah \hoomPahHoomPah \hoomPahHoomPah
+ \stemdown [c8 c'8] r4
+ <g d'> r4
+ < {\stemup r2 <e4 c'> <c8 g'> }
+ \context Voice = reallyLow {\stemdown g2 ~ | g4 c8 } >
+}
+
+\score {
+ \context PianoStaff \notes <
+ \context Staff = top < \time 2/2;
+ \context Voice = viola \viola
+ \oboes
+ >
+ \context Staff = bottom < \time 2/2; \clef bass;
+ \bassvoices
+ >
+ >
+ \midi { }
+ \paper {
+ indent = 0.0;
+ linewidth = 15.0 \cm; }
+}
+@end mudela
+
+If it looks like incomprehensible gibberish to you@dots{} Then you are
+right. The author has doctored this example to have as many quirks in
+one system as possible.@example
+viola = \notes \relative c' \context Voice = viola @{
+@end example
+In this example, you can see multiple parts on a staff. Each part is
+associated with one notation context. This notation context handles
+stems and dynamics (among others). The name of this context is
+@code{Voice}. For each part we have to make sure that there is
+precisely one Voice context@footnote{If @code{\context} would not
+have been specified explicitly, three @code{Voice} contexts would be
+created: one for each note in the first chord.}.@example
+<c4-\f g' c>
+@end example
+@code{<} and @code{>} are short hands for @code{\simultaneous @{} and
+@code{@}}. So the expression enclosed in @code{<} and @code{>} is a
+chord. @code{\f} places a forte symbol under the chord.@example
+\property Voice.verticalDirection = \down
+@end example
+@code{verticalDirection} is a property of the voice context. It
+controls the directions of stems, articulations marks and other
+symbols.
+ If @code{verticalDirection} is set to @code{\down}
+(identifier for the integer -1) the stems go down,
+@code{\up} (identifier for the integer 1) makes the stems go up.@example
+ g'8. b,16
+@end example
+Relative octaves work a little differently with chords. The starting
+point for the note following a chord is the first note of the chord. So
+the @code{g} gets an octave up quote: it is a fifth above the starting
+note of the previous chord (the central C).
+
+@example
+s1 s2. r4
+@end example
+@code{s} is a `spacer' rest. It does not print anything, but it does
+have the duration of a rest. @example
+oboes = \notes \relative c'' \context Voice = oboe @{
+@end example
+Now comes a part for two oboes. They play homophonically, so we
+print the notes as one voice that makes chords. Again, we insure that
+these notes are indeed processed by precisely one context with
+@code{\context}.@example
+\stemup s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
+@end example
+@code{\stemup} is an identifier reference. It is shorthand for
+@code{\property Voice.verticalDirection = \up}. If possible, you
+should use predefined identifiers like these for setting properties.
+Your input will be less dependent upon the implementation of LilyPond.
+@example
+\grace <e8( g> < )d4 f> <c2 e>
+@end example
+@code{\grace} introduces grace notes. It takes one argument, in this
+case a chord. The slur started on the @code{e} of the chord
+will be attached to the next note.@footnote{LilyPond will squirm
+about unended Slurs. In this case, you can ignore the warning}.
+@example
+\times 2/3
+@end example
+Tuplets are made with the @code{\times} keyword. It takes two
+arguments: a fraction and a piece of music. The duration of the
+second argument is multiplied by the first argument. Triplets make
+notes occupy 2/3 of their notated duration, so in this case the
+fraction is 2/3. @example
+@{ <d8 \< f> <e g> <f a> @}
+@end example
+The piece of music to be `tripletted' is sequential music containing
+three notes. On the first chord (the @code{d}), a crescendo is started
+with @code{\<}.@example
+<
+@end example
+At this point, the homophonic music splits into two rhythmically
+different parts. We can't use a sequence of chords to enter this, so
+we make a `chord' of sequences to do it. We start with the upper
+voice, which continues with upward stems: @example
+ @{ \times 2/3 @{ a8 g c @} \! c2 @}
+@end example
+The crescendo is ended at the half note by the escaped exclamation
+mark `@code{\!}'. @example
+\context Voice = oboeTwo @{
+\stemdown
+@end example
+We can't share stems with the other voice, so we have to create a new
+@code{Voice} context. We give it the name @code{oboeTwo} to distinguish
+it from the other context. Stems go down in this voice. @example
+\grace @{
+@end example
+When a grace section is processed, a @code{Grace} context is
+created. This context acts like a miniature score of its own. It has
+its own time bookkeeping, and you can make notes, beams, slurs
+etc. Here fiddle with a property and make a beam. The argument of
+@code{\grace} is sequential music.@example
+\property Grace.verticalDirection = \down
+[f,16 g] @}
+@end example
+Normally, grace notes are always stem up, but in this case, the upper
+voice interferes. We set the stems down here.
+
+As far as relative mode is concerned, the previous note is the
+@code{c'''2} of the upper voice, so we have to go an octave down for
+the @code{f}.
+@example
+
+ f8 e e2
+@} >
+@end example
+This ends the two-part section. @example
+\stemboth
+\grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
+@end example
+@code{\stemboth} ends the forced stem directions. From here, stems are
+positioned as if it were single part music.
+
+The bass has a little hoom-pah melody to demonstrate parts switching
+between staffs. Since it is repetitive, we use identifiers:@example
+hoomPah = \notes \transpose c' @{
+@end example
+Transposing can be done with @code{\transpose}. It takes two
+arguments; the first specifies what central C should be transposed to.
+The second is the to-be-transposed music. As you can see, in this
+case, the transposition is a no-op. Central C is transposed to
+central C.
+
+The purpose of this no-op is circumventing relative mode. Relative
+mode can not be used in conjunction with transposition, so relative
+mode will leave the contents of @code{\hoomPah} alone. We can use it
+without having to worry about getting the motive in a wrong
+octave@footnote{@code{hoomPah = \relative @dots{}} would be more
+intuitive to use, but that would not let me plug @code{\transpose}
+:-).}.@example
+c8 \translator Staff = top \stemdown
+@end example
+We assume that the first note will be put in the lower staff. After
+that note we switch to the upper staff with @code{\translator}. To be
+precise, this @code{\translator} entry switches the current voice to a
+@code{Staff} named @code{top}. So we have to name the upper staff
+`@code{top}'. Stem directions are set to avoid interfering with the
+oboe voices. @example
+c'8 \translator Staff = bottom \stemup @}
+@end example
+Then a note is put on the upper staff, and we switch again. We have
+to name the lower staff `@code{bottom}'. @example
+hoomPahHoomPah = @{ [\hoomPah \hoomPah] @}
+@end example
+Put two of these fragments in sequence, and beam them.@example
+bassvoices = \notes \relative c' @{
+c4 g8. b,16
+\hoomPahHoomPah \hoomPahHoomPah \hoomPahHoomPah
+\hoomPahHoomPah
+@end example
+Entering the bass part is easy: the hoomPahHoomPah variable is
+referenced four times.@example
+\context Voice = reallyLow @{\stemdown g2 ~ | g4 c8 @} >
+@end example
+After skipping some lines, we see @code{~}. This mark makes ties.@example
+\context PianoStaff
+@end example
+For piano music, a special context is needed to get cross staff
+beaming right. It is called @code{PianoStaff}.@example
+\context Staff = bottom < \time 2/2; \clef bass;
+@end example
+The bottom staff must have a different clef.@example
+indent = 0.0;
+@end example
+To make some more room on the line, the first (in this case the only)
+line is not indented. The line still looks is very cramped, but that is due
+to the format of this tutorial.
+
+This example shows a lot of features, but the organisation isn't
+perfect. For example, it would be less confusing to use a chord
+containing sequential music than a sequence of chords for the oboe
+parts.
+
+[TODO: demonstrate Hara-Kiri with scores and part extraction.]
+
+@node end of tutorial, , , Tutorial
+@section The end
+
+That's all folks. From here, you can either try fiddling with input
+files, or you can read the reference manual.
+
+
+
+
+
+
+@node Reference Manual, , , Top
+@menu
+* Overview:: Overview
+* Top level:: Top level
+* notenames:: notenames
+* Lexical conventions:: Lexical conventions
+* notelang:: notelang
+* modes:: modes
+* Types:: Types
+* Music expressions:: Music expressions
+* Atomic music expressions:: Atomic music expressions
+* atomicmusic:: atomicmusic
+* notedesc:: notedesc
+* barlines:: barlines
+* manualbeam:: manualbeam
+* tremolo:: tremolo
+* Compound music expressions:: Compound music expressions
+* compoundmusic:: compoundmusic
+* relative:: relative
+* sec-repeats:: sec-repeats
+* transpose:: transpose
+* Ambiguities:: Ambiguities
+* Notation conversion specifics:: Notation conversion specifics
+* autobeam:: autobeam
+* lyricprint:: lyricprint
+* Notation Contexts:: Notation Contexts
+* contextselection:: contextselection
+* Notation output definitions:: Notation output definitions
+* output:: output
+* paper:: paper
+* papervars:: papervars
+* contextdefs:: contextdefs
+* engravers:: engravers
+* Sound output:: Sound output
+* midilist:: midilist
+* Pre-defined Identifiers:: Pre-defined Identifiers
+* Running LilyPond:: Running LilyPond
+@end menu
+
+@chapter Reference Manual
+
+
+
+@node Overview, , , Reference Manual
+@section Overview
+
+This document@footnote{This document has been revised for
+LilyPond 1.2.} describes the the GNU LilyPond input format, which is
+a language for defining music. We call this language @emph{Music
+Definition Language} or @emph{Mudela}, for short.@footnote{If anybody
+comes up with a better name, we'd gladly take this. Gourlay already
+uses a ``Musical Description Language,'' ISO standard 10743 defines a
+``Standard Music Description Language.'' We're not being original
+here.}
+
+@emph{Mudela} is a language that allows you to
+
+@itemize @bullet
+ @item create musical expressions by combining pitches, durations
+ @item output those musical expressions to various formats
+ @item give those musical expressions and output definitions names, so
+ you can enter them in manageable chunks.
+@end itemize
+
+@emph{Mudela} aims to define a piece of music completely, both from
+typesetting and from a performance point of view.
+
+
+
+@node Top level, , , Reference Manual
+@section Top level
+
+@cindex top level
+
+This section describes what you may enter at top level.
+
+
+
+@cindex score definition
+
+The output is generated combining a music expression with an output
+definition. A score block has the following syntax:
+
+@example
+ \score @{ @var{musicexpr} @var{outputdefs} @}
+@end example
+
+@var{outputdefs} are zero or more output definitions. If no output
+definition is supplied, the default @code{\paper} block will be added.
+
+
+
+@cindex header
+
+@keyindex{header}
+
+The syntax is
+
+@example
+ \header @{ @var{key1} = @var{val1};
+ @var{key2} = @var{val2}; @dots{} @}
+@end example
+
+A header describes the file's contents. It can also appear in a
+@code{\score} block. Tools like @code{ly2dvi}@indexcode{ly2dvi} can use this
+information for generating titles. Key values that are used by
+@code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument,
+metre, arranger, piece and tagline.
+
+It is customary to put the @code{\header} at the top of the file.
+
+
+@node notenames, , , Reference Manual
+
+Note name tables can be specified using
+
+@example
+ \notenames@keyindex{notenames}
+ @{ @var{assignmentlist} @}
+@end example
+
+@var{assignmentlist} is a list of definitions of the form
+
+@example
+ @var{name} = @var{pitch}
+@end example
+
+Chord modifiers can be set analogously, with
+@code{\chordmodifiers}@keyindex{chordmodifiers}.
+
+A @code{\paper} block at top level sets the default paper block. A
+@code{\midi} block at top level works similarly.
+
+
+
+LilyPond contains a Scheme interpreter (the GUILE library) for
+internal use. The following commands access the interpreter
+directly.
+
+@example
+ \scm @keyindex{scm} @var{scheme} ;
+@end example
+
+Evaluates the specified Scheme code. The result is discarded.
+
+@example
+\scmfile@keyindex{scmfile} @var{filename};
+@end example
+
+Reads Scheme code from the specified file. The result is discarded.
+
+
+
+Identifier assignments may appear at top level. Semicolons are
+forbidden after top level assignments.
+
+
+
+@node Lexical conventions, , , Reference Manual
+@section Lexical conventions
+
+@cindex lexical conventions
+
+
+
+@cindex comment
+
+@indexcode{%}
+
+
+A one line comment is introduced by a `@code{%}' character.
+Block comments are started by `@code{%@{}' and ended by `@code{%@}}'.
+They cannot be nested.
+
+
+
+@cindex keyword
+
+Keywords start with a backslash, followed by a number of lower case
+alphabetic characters. These are all the keywords.
+
+@example
+ \accepts
+ \addlyrics
+ \alternative
+ \bar
+ \breathe
+ \cadenza
+ \chordmodifiers
+ \chords
+ \clef
+ \cm
+ \consists
+ \consistsend
+ \context
+ \duration
+ \font
+ \grace
+ \header
+ \in
+ \key
+ \keysignature
+ \lyrics
+ \mark
+ \midi
+ \mm
+ \musicalpitch
+ \name
+ \notenames
+ \notes
+ \paper
+ \partial
+ \penalty
+ \property
+ \pt
+ \relative
+ \remove
+ \repeat
+ \repetitions
+ \scm
+ \scmfile
+ \score
+ \script
+ \sequential
+ \shape
+ \simultaneous
+ \skip
+ \spanrequest
+ \tempo
+ \textscript
+ \time
+ \times
+ \translator
+ \transpose
+ \type
+@end example
+
+
+
+
+@cindex integer
+
+Formed from an optional minus sign followed by digits. Arithmetic
+operations cannot be done with integers, and integers cannot be mixed
+with reals.
+
+
+
+@cindex real
+
+
+Formed from an optional minus sign and a sequence of digits followed
+by a @emph{required} decimal point and an optional exponent such as
+@code{-1.2e3}. Reals can be built up using the usual operations:
+`@code{+}@indexcode{+}', `@code{-}@indexcode{-}', `@code{*}@indexcode{*}', and
+`@code{/}@indexcode{/}', with parentheses for grouping.
+
+A real constant can be followed by one of the dimension
+keywords:
+@cindex dimensions
+ @code{\mm}@keyindex{mm},
+@code{\pt}@keyindex{pt}, @code{\in}@keyindex{in}, or
+@code{\cm}@keyindex{cm}, for millimeters, points, inches and
+centimeters, respectively. This converts the number to a real that
+is the internal representation of dimensions.
+
+
+
+@cindex string
+
+
+Begins and ends with the `@code{"}' character. To include a `@code{"}'
+character in a string write `@code{\"}'. Various other backslash
+sequences have special interpretations as in the C language. A
+string that contains no spaces can be written without the quotes.
+See section XREF-modes [FIXME] for details on unquoted strings; their
+interpretation varies depending on the situation. Strings can be
+concatenated with the `@code{+}' operator.
+
+
+The tokenizer accepts the following commands. They can appear
+anywhere.
+
+@example
+ \maininput@keyindex{maininput}
+@end example
+
+This command is used in init files to signal that the user file must
+be read. This command cannot be used in a user file.
+
+@example
+ \include@keyindex{include} @var{file}
+@end example
+
+Include @var{file}. The argument @var{file} may be a quoted string (an
+unquoted string will not work here!) or a string identifier. The full
+filename including the @file{.ly} extension must be given,
+
+@example
+ \version@keyindex{version} @var{string} ;
+@end example
+
+Specify the version of LilyPond that a file was written for. The
+argument is a version string in quotes, for example @code{"1.2.0"}.
+This is used to detect invalid input, and to aid
+@code{convert-mudela}, a tool that automatically upgrades input files.
+
+
+
+@cindex other languages
+
+@node notelang, , , Reference Manual
+
+Note name definitions have been provided in various languages.
+Simply include the language specific init file. For example:
+`@code{\include "english.ly"}'. The available language files and the
+names they define are:
+
+@quotation
+
+@example
+ Note Names sharp flat
+nederlands.ly c d e f g a bes b -is -es
+english.ly c d e f g a bf b -s/-sharp -f/-flat
+deutsch.ly c d e f g a b h -is -es
+norsk.ly c d e f g a b h -iss/-is -ess/-es
+svenska.ly c d e f g a b h -iss -ess
+italiano.ly do re mi fa sol la sid si -d -b
+catalan.ly do re mi fa sol la sid si -d/-s -b
+@end example
+
+@end quotation
+
+Pitch names can be redefined using the
+@code{\notenames}@keyindex{notenames} command, see
+subsection XREF-notenames [FIXME].
+
+
+
+@cindex lexical modes
+
+@cindex modes
+
+@node modes, , , Reference Manual
+
+To simplify entering notes, lyrics, and chords, @emph{Mudela} has three
+special input modes on top of the default mode. In each mode, words
+are identified on the input. If @code{"word"} is encountered, it is
+treated as a string. If @code{\word} is encountered, it is treated as
+a keyword or as an identifier. The behavior of the modes differs in
+two ways: Different modes treat unquoted words differently, and
+different modes have different rules for deciding what is a word.
+
+@table @samp
+ @item Normal mode.
+@cindex mode!normal
+
+ At the start of parsing, @emph{Mudela} is in Normal mode. In Normal
+ mode, a word is an alphabetic character followed by alphanumeric
+ characters. If @code{word} is encountered on the input it is
+ treated as a string.
+
+ @item Note mode.
+@cindex mode!note
+
+ Note mode is introduced by the keyword
+ @code{\notes}@keyindex{notes}. In Note mode, words can only
+ contain alphabetic characters. If @code{word} is encountered,
+ LilyPond first checks for a notename of @code{word}. If no
+ notename is found, then @code{word} is treated as a string.
+
+ Since combinations of numbers and dots are used for indicating
+ durations, it is not possible to enter real numbers in this mode.
+
+ @item Chord mode.
+@cindex mode!chord
+
+ Chord mode is introduced by the keyword
+ @code{\chords}@keyindex{chords}. It is similar to Note mode, but
+ words are also looked up in a chord modifier table (containing
+ @code{maj}, @code{dim}, etc).
+
+ Since combinations of numbers and dots are used for indicating
+ durations, you can not enter real numbers in this mode. Dashes
+ and carets are used to indicate chord additions and subtractions,
+ so scripts can not be entered in Chord mode.
+
+ @item Lyrics mode.
+@cindex mode!lyric
+
+ Lyrics mode is introduced by the keyword
+ @code{\lyrics}@keyindex{lyrics}. This mode has rules that make it
+ easy to include punctuation and diacritical marks in words. A
+ word in Lyrics mode begins with: an alphabetic character,
+ `@code{_}', `@code{?}', `@code{!}', `@code{:}', `@code{'}', the
+ control characters @code{^A} through @code{^F}, @code{^Q} through
+ @code{^W}, @code{^Y}, @code{^^}, any 8-bit character with ASCII code
+ over 127, or a two-character combination of a backslash followed
+ by one of `@code{`}', `@code{'}', `@code{"}', or
+ `@code{^}'.@footnote{The purpose of Lyrics mode is that you can
+ enter lyrics in TeX format or a standard encoding without
+ needing quotes. The precise definition of this mode indeed is
+ ludicrous. This will remain so until the authors of LilyPond
+ acquire a deeper understanding of character encoding, or someone
+ else steps up to fix this.}
+
+ Subsequent characters of a word can be any character that is not
+ a digit and not white space. One important consequence of this
+ is that a word can end with `@code{@}}', which may be confusing if
+ you thought the closing brace was going to terminate Lyrics
+ mode.@footnote{LilyPond will issue a warning, though.} Any
+ `@code{_}' characters which appear in an unquoted word are
+ converted to spaces. This provides a mechanism for introducing
+ spaces into words without using quotes. Quoted words can also be
+ used in Lyrics mode to specify words that cannot be written with
+ the above rules. Here are some examples. Not all of these words
+ are printable by TeX.
+
+
+ @quotation
+
+@example
+Ah! % a word
+2B_||_!2B % not a word because it starts with a digit
+``Hello'' % not a word because it starts with `
+_ _ _ _ % 4 words, each one a space
+@end example
+
+ @end quotation
+
+ Since combinations of numbers and dots are used for indicating
+ durations, you can not enter real numbers in this mode.
+@end table
+
+It is possible to create words that break the rules by prefixing them
+with the dollar sign `@code{$}@indexcode{$}'. Regardless of the context, a
+word beginning with `@code{$}' extends until the next white space
+character. Such words can contain numbers (even in Note mode), or
+other forbidden characters. The dollar sign can be used to create
+and access identifiers that could not otherwise be used.@footnote{Use
+of `@code{$}' hampers readability and portability to future LilyPond
+versions, thus the use of the dollar sign is discouraged.}
+
+
+
+@node Types, , , Reference Manual
+@section Types
+
+@cindex types and identifiers
+
+@emph{Mudela} has a limited set of types:
+
+@itemize @bullet
+ @item integers
+ @item reals
+ @item strings
+ @item music expressions
+ @item durations of notes and rests (specified with
+ @code{\notenames}@keyindex{notenames})
+ @item note name tables
+ @item context definitions, part of output definitions. See
+ section XREF-contextdefs [FIXME] for more information
+ @item output definitions (like @code{\paper}@keyindex{paper} blocks
+ and @code{\midi}@keyindex{midi} blocks)
+ @item score definitions (@code{\score}@keyindex{score} blocks)
+@end itemize
+
+Type is a syntactical property: @emph{Mudela} has no real type system,
+so there is no support for generic expressions, functions, or user
+defined types. For the same reason, it is not possible to mix reals
+and integers in arithmetic expressions, and ``type
+errors''
+@cindex type error
+ (e.g., using a string identifier to
+initialize a @code{\paper}@keyindex{paper} block) will yield a ``parse
+error''.
+
+Identifiers allow objects to be assigned to names. To assign an
+identifier, you use `@var{name}=@var{value}' and to refer to an
+identifier, you preceed its name with a backslash:
+`@code{\}@var{name}'. Identifier assignments must appear at top level
+in the @emph{Mudela} file. Semicolons are forbidden after assignments
+appearing at top level but they are obligatory after assignments
+appearing in the @code{\paper} block, see Section XREF-paper [FIXME].
+
+@var{value} is any of the types listed above.
+
+An identifier can be created with any string for its name, but you
+will only be able to refer to identifiers whose names begin with a
+letter, being entirely alphanumeric. It is impossible to refer to an
+identifier whose name is the same as the name of a keyword.
+
+The right hand side of an identifier assignment is parsed completely
+before the assignment is done, so it is allowed to redefine an
+identifier in terms of its old value, e.g.
+
+@example
+ foo = \foo * 2.0
+@end example
+
+When an identifier is referenced, the information it points to is
+copied. Therefore it only makes sense to put identifiers for
+translators, output definitions, and @code{\score}@keyindex{score}
+blocks as the first item in a block. For this reason, if you
+reference a @code{\foo} variable in a @code{\foo} block, it must be the
+first item in the list following @code{\foo}.@footnote{@code{\paper@{\one
+\two@}} does not make sense, because the information of @code{\two}
+would overwrite the information of @code{\one}, thereby making the
+reference to the first identifier useless.}
+
+
+
+@node Music expressions, , , Reference Manual
+@section Music expressions
+
+@cindex music expressions
+
+Music in @emph{Mudela} is entered as a music expression. Notes, rests,
+lyric syllables are music expressions (the atomic
+expressions)
+@cindex atomic music expressions
+, and you can combine
+music expressions to form new ones. This example forms a compound
+expressions out of the quarter @code{c} note and a @code{d}
+note:
+
+@example
+\sequential @{ c4 d4 @}
+@end example
+
+The meaning of this compound expression is to play the `@code{c}'
+first, and then the `@code{d}' (as opposed to playing them
+simultaneously, for instance).
+
+Atomic music expression are discussed in
+subsection XREF-atomicmusic [FIXME]. Compound music expressions are
+discussed in subsection XREF-compoundmusic [FIXME].
+
+
+
+@node Atomic music expressions, , , Reference Manual
+@section Atomic music expressions
+@node atomicmusic, , , Reference Manual
+
+
+
+@cindex pitch
+
+@cindex duration
+
+
+The syntax for pitch specification is
+
+
+@example
+ \musicalpitch@keyindex{musicalpitch} @{ @var{octave} @var{note} @var{shift} @}
+@end example
+
+@var{octave} is specified by an integer, zero for the octave
+containing middle C. @var{note} is a number from 0 to 7, with 0
+corresponding to C and 7 corresponding to B. The shift is zero for a
+natural, negative to add flats, or positive to add sharps.
+
+In Note and Chord mode, pitches may be designated by names. See
+section XREF-notelang [FIXME] for pitch names in different languages.
+
+The syntax for duration specification is
+
+@example
+ \duration@keyindex{duration}
+ @{ @var{length} @var{dotcount} @}
+@end example
+
+@var{length} is the negative logarithm (base 2) of the duration:
+1 is a half note, 2 is a quarter note, 3 is an eighth
+note, etc. The number of dots after the note is given by
+@var{dotcount}.
+
+In Note, Chord, and Lyrics mode, durations may be designated by
+numbers and dots. See Section XREF-notelang [FIXME] for details.
+
+
+@node notedesc, , , Reference Manual
+
+@cindex note specification
+
+@cindex pitches
+
+@cindex entering notes
+
+A note specification has the form
+
+@example
+ @var{pitch}[@var{octavespec}][!][?][@var{duration}]
+@end example
+
+The pitch of the note is specified by the note's name.
+
+
+The default names are the Dutch note names. The notes are specified
+by the letters `@code{c}' through `@code{b}', where `@code{c}' is an
+octave below middle C and the letters span the octave above that C.
+In Dutchcindex(notenames!Dutch), a sharp is formed by adding
+`@code{-is}' to the end of a pitch name. A flat is formed by adding
+`@code{-es}'. Double sharps and double flats are obtained by adding
+`@code{-isis}' or `@code{-eses}'. `@code{aes}' and `@code{ees}' are
+contracted to `@code{as}' and `@code{es}' in Dutch, but both forms will
+be accepted.
+
+LilyPond has predefined sets of notenames for various languages. See
+section XREF-notelang [FIXME] for details.
+
+
+The optional octave specification takes the form of a series of
+single quote (`@code{'}@indexcode{'}') characters or a series of comma
+(`@code{,}@indexcode{,}') characters. Each @code{'} raises the pitch by one
+octave; each @code{,} lowers the pitch by an octave.
+
+@mudela[fragment,verbatim,center]
+ c' d' e' f' g' a' b' c''
+@end mudela
+
+@mudela[fragment,verbatim,center]
+ cis' dis' eis' fis' gis' ais' bis'
+@end mudela
+
+@mudela[fragment,verbatim,center]
+ ces' des' es' fes' ges' as' bes'
+@end mudela
+
+@mudela[fragment,verbatim,center]
+ cisis' eisis' gisis' aisis' beses'
+@end mudela
+
+@mudela[fragment,verbatim,center]
+ ceses' eses' geses' ases' beses'
+@end mudela
+
+Whenever a C-sharp is desired, you must specify a C-sharp. LilyPond
+will determine what accidentals to typeset depending on the key and
+context. A reminder accidental
+@cindex reminder accidental
+ can be
+forced by adding an exclamation mark `@code{!}' after the pitch. A
+cautionary accidental,
+@cindex cautionary accidental
+ i.e., an
+accidental within parentheses can be obtained by adding the question
+mark `@code{?}@indexcode{?}' after the pitch.
+
+@mudela[fragment,verbatim,center]
+ cis' d' e' cis' c'? d' e' c'!
+@end mudela
+
+
+@cindex duration
+
+Durations are entered as their reciprocal values. For notes longer
+than a whole note, use identifiers.
+
+@quotation
+
+@example
+c'\longa c'\breve
+c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
+@end example
+
+@end quotation
+
+@quotation
+
+@mudela[]
+\score {
+ \notes \relative c'' {
+ a\longa a\breve
+ a1 a2 a4 a8 a16 a32 a64 a64
+ }
+ \paper {
+ loose_column_distance = 2.5 * \interline;
+ linewidth = -1.0;
+ \translator {
+ \type "Score_engraver";
+ \name "Score";
+ \consists "Note_heads_engraver";
+ \consists "Stem_engraver";
+ \consists "Rhythmic_column_engraver";
+ }
+ }
+}
+@end mudela
+@end quotation
+
+@quotation
+
+@example
+r\longa r\breve
+r1 r2 r4 r8 r16 r32 r64 r64
+@end example
+
+@end quotation
+
+@quotation
+
+@mudela[]
+\score {
+ \notes \relative c'' {
+ r\longa r\breve
+ r1 r2 r4 r8 r16 r32 r64 r64
+ }
+ \paper {
+ loose_column_distance = 2.5 * \interline;
+ linewidth = -1.0;
+ \translator {
+ \type "Score_engraver";
+ \name "Score";
+ \consists "Rest_engraver";
+ \consists "Stem_engraver";
+ \consists "Rhythmic_column_engraver";
+ }
+ }
+}
+@end mudela
+@end quotation
+
+If the duration is omitted then it is set equal to the previous
+duration. If there is no previous duration, a quarter note is
+assumed. The duration can be followed by a dot (`@code{.}@indexcode{.}')
+to obtain dotted note lengths.
+
+@mudela[fragment,verbatim,center]
+ a'4. b'4.
+@end mudela
+
+You can alter the length of duration by writing
+`@code{*}@var{fraction}' after it. This will not affect the
+appearance of note heads or rests.
+
+
+Rests are entered like notes, with note name `@code{r}@indexcode{r}',
+or `@code{R}@indexcode{R}'. There is also a note name `@code{s}@indexcode{s}',
+which produces a space of the specified duration.
+`@code{R}' is specifically meant for entering parts: the @code{R} rest
+can expand to fill a score with rests, or it can be printed as a
+single multimeasure rest.
+
+
+@cindex lyrics expressions
+
+Syllables are entered like notes, with pitches replaced by text. For
+example, `@code{Twin-4 kle4 twin-4 kle4}' enters four syllables, each
+with quarter note duration. Note that the hyphen has no special
+meaning for lyrics, and does not introduce special symbols. See
+section XREF-modes [FIXME] for a description of what is interpreted as
+lyrics.
+
+Spaces can be introduced into a lyric either by using quotes
+(`@code{"}') or by using an underscore without quotes: `@code{He_could4
+not4}'. All unquoted underscores are converted to spaces. Printing
+lyrics is discussed in section XREF-lyricprint [FIXME].
+
+
+
+@cindex properties
+
+@example
+ \property@keyindex{property}
+ @var{contextname}.@var{propname} = @var{value}
+@end example
+
+Sets the @var{propname} property of the context @var{contextname} to
+the specified @var{value}. All three arguments are strings.
+Depending on the context, it may be necessary to quote the strings or
+to leave space on both sides of the dot.
+
+
+
+@cindex translator switches
+
+@example
+ \translator@keyindex{translator}
+ @var{contexttype} = @var{name}
+@end example
+
+A music expression indicating that the context which is a direct
+child of the a context of type @var{contexttype} should be shifted to
+a context of type @var{contexttype} and the specified name.
+
+Usually this is used to switch staffs in Piano music, e.g.
+
+@example
+ \translator Staff = top @var{Music}
+@end example
+
+
+
+@cindex commands
+
+Commands are music expressions that have no duration.
+
+
+@example
+
+ @code{\key}@keyindex{key} @var{pitch} @var{type} @code{;}
+@end example
+
+Change the key signature. @var{type} should be
+@code{\major}@keyindex{major} or @code{\minor}@keyindex{minor} to get
+@var{pitch}-major or @var{pitch}-minor, respectively. The second
+argument is optional; the default is major keys. The @var{\context}
+argument can also be given as an integer, which tells the number of
+semitones that should be added to the pitch given in the subsequent
+@code{\key}@keyindex{key} commands to get the corresponding major key,
+e.g., @code{\minor}@keyindex{minor} is defined as 3. The standard
+mode names @code{\ionian}@keyindex{ionian},
+@code{\locrian}@keyindex{locrian}, @code{\aeolian}@keyindex{aeolian},
+@code{\mixolydian}@keyindex{mixolydian}, @code{\lydian}@keyindex{lydian},
+@code{\phrygian}@keyindex{phrygian}, and @code{\dorian}@keyindex{dorian}
+are also defined.
+
+@example
+
+ @code{\keysignature}@keyindex{keysignature} @var{pitchseq} @code{;}
+@end example
+
+Specify an arbitrary key signature. The pitches from @var{pitch} will
+be printed in the key signature in the order that they appear on the
+list.
+
+
+@example
+ \mark@keyindex{mark} @var{unsigned};
+ \mark @var{string};
+@end example
+
+Prints a mark over or under (depending on the
+@code{markDirection}@indexcode{markDirection} property) the staff. You must add
+@code{Mark_engraver}@indexcode{Mark_engraver} to either the Score or Staff context for
+this to work.
+
+@node barlines, , , Reference Manual
+
+@example
+ \bar@keyindex{bar} @var{bartype};
+@end example
+
+This is a request to print a special bar symbol. It replaces the
+regular bar symbol with a special
+symbol. The argument @var{bartype} is a string which specifies the
+kind of bar to print. Options are @code{":|"}
+@cindex "|A@@@code{:|}
+,
+@code{"|:"}
+@cindex "|B@@@code{|:}
+, @code{":|:"}
+@cindex "|C@@@code{:|:}
+,
+@code{"||"}
+@cindex "|D@@@code{||}
+, @code{"|."}
+@cindex "|E@@@code{|.}
+,
+@code{".|"}
+@cindex "|F@@@code{.|}
+, and @code{".|."}
+@cindex "|G@@@code{.|.}
+.
+These produce, respectively, a right repeat, a left repeat, a double
+repeat, a double bar, a start bar, an end bar, and a thick double
+bar. If @var{bartype} is set to @code{"empty"} then nothing is
+printed, but a line break is allowed at that spot.
+
+You are encouraged to use @code{\repeat} for repetitions.
+See section XREF-sec-repeats [FIXME].
+
+
+
+@example
+ \cadenza@keyindex{cadenza} @var{togglevalue} @code{;}
+@end example
+
+Music expression that toggles the automatic generation of bar lines.
+If @var{togglevalue} is 1, bar line generation is turned off. If
+@var{togglevalue} is 0, a bar line is immediately printed and
+automatic bar generation is turned on.
+
+@example
+
+ \time@keyindex{time} @var{numerator}@code{/}@var{denominator} @code{;}
+@end example
+
+Change the time signature. The default time signature is 4/4.
+The time signature is used to generate bar lines.
+
+@example
+
+ \tempo@keyindex{tempo} @var{duration} = @var{perminute} @code{;}
+@end example
+
+Used to specify the tempo. For example, `@code{\tempo 4 = 76;}'
+requests output with 76 quarter notes per minute.
+
+@example
+
+ \partial@keyindex{partial} @var{duration} @code{;}
+@end example
+
+@cindex anacrusis
+
+@cindex upstep
+
+This creates an incomplete measure (anacrusis, upbeat) at the start of
+the music, e.g., `@code{\partial 8*2;}' creates a starting measure
+lasting two eighth notes.
+
+@example
+
+ @code{|}@indexcode{|}
+@cindex bar check
+
+@end example
+
+@cindex shorten measures
+
+@cindex upstep
+
+`@code{|}' is a barcheck. Whenever a barcheck is encountered during
+interpretation, a warning message is issued if it doesn't fall at a
+measure boundary. This can help you finding errors in the input.
+The beginning of the measure will be relocated, so this can also
+be used to shorten measures.
+
+
+@example
+
+ \penalty@keyindex{penalty} @var{int} @code{;}
+@end example
+
+Discourage or encourage line breaks. See identifiers
+@code{\break}@keyindex{break} and @code{\nobreak}@keyindex{nobreak} in
+section [on identifiers] [FIXME].
+
+@example
+
+ \clef@keyindex{clef} @var{clefname} @code{;}
+@end example
+
+Music expression that sets the current clef. The argument is a
+string which specifies the name of the clef. Several clef names are
+supported. If `@code{_8}' or `@code{^8}' is added to the end of a clef
+name, then the clef lowered or raised an octave will be generated.
+Here are the supported clef names with middle C shown in each
+clef:
+
+@quotation
+
+@mudela[]
+\score {
+ \notes {
+ \cadenza 1;
+ %\property Voice.textStyle = typewriter
+ \clef subbass; c'4-"\kern -5mm subbass"
+ \clef bass; c'4^"\kern -2mm bass"
+ \clef baritone; c'4_"\kern -5mm baritone"
+ \clef varbaritone; c'4^"\kern -6mm varbaritone"
+ \clef tenor; c'4_"\kern -3mm tenor"
+ \clef "G_8"; c'4^"\kern -2mm G\\_8"
+ }
+ \paper {
+ linewidth = 4.5 \in;
+ }
+}
+@end mudela
+@end quotation
+
+@quotation
+
+@mudela[]
+\score {
+ \notes {
+ \cadenza 1;
+ \clef alto; c'4_"\kern -2mm alto"
+ \clef mezzosoprano; c'4^"\kern -9mm mezzosoprano"
+ \clef soprano; c'4_"\kern -6mm soprano"
+ \clef treble; c'4^"\kern -4mm treble"
+ \clef french; c'4_"\kern -4mm french"
+ }
+ \paper {
+ linewidth = 4.5 \in;
+ }
+}
+@end mudela
+@end quotation
+
+The three clef symbols can also be obtained using the names `@code{G}',
+`@code{C}' or `@code{F}', optionally followed by an integer which
+indicates at which note line the clef is located. An as example, the
+@code{mezzosoprano} clef can also be given as `@code{C2}'.
+
+@example
+
+ \skip@keyindex{skip} @var{duration} @code{;}
+@end example
+
+Skips the amount of time specified by @var{duration}. If no other
+music is played, a gap will be left for the skipped time with no
+notes printed. It works in Note Mode or Lyrics Mode. In Note mode,
+this has the same effect as the space rest `@code{s}'.
+
+
+@cindex beams
+
+@node manualbeam, , , Reference Manual
+
+A beam is specified by surrounding the beamed notes with brackets
+`@code{[}@indexcode{[}' and `@code{]}@indexcode{]}'.
+
+@mudela[fragment,verbatim,center]
+ [a'8 a'] [a'16 a' a' a']
+@end mudela
+
+Some more elaborate constructions:
+
+@mudela[fragment,verbatim,center]
+ [a'16 <a' c''> c'' <a' c''>]
+ \times 2/3 { [e'8 f' g'] }
+@end mudela
+
+Beaming can be generated automatically; see section XREF-autobeam [FIXME].
+
+To place tremolo marks
+@cindex tremolo beams
+ between two notes, begin
+with `@code{[:}@var{length}' and end with `@code{]}'. Tremolo marks
+will appear instead of beams. Putting more than two notes in such a
+construction will produce odd effects. To create tremolo beams on a
+single note, simply attach `@code{:}@var{length}' to the note itself
+(see also section XREF-tremolo [FIXME]).
+
+@mudela[fragment,verbatim,center]
+ [:16 e'1 g'] [:8 e'4 f']
+@end mudela
+
+@mudela[fragment,verbatim,center]
+ c'4:32 [:16 c'8 d'8]
+@end mudela
+
+
+@cindex --@@@code{-}@code{-}
+
+@indexcode{__}
+
+@cindex extender
+
+@cindex hyphen
+
+The syntax for an extender mark is `@code{__}'. This syntax can only
+be used within lyrics mode. The syntax for a spanning hyphen (i.e.,
+a hyphen that will be printed between two lyric syllables) is
+`@code{-}@code{-}'.
+
+
+@cindex ties
+
+A tie connects two adjacent note heads of the same pitch. When used
+with chords, it connects all of the note heads whose pitches match.
+Ties are indicated using the tilde symbol `@code{~}@indexcode{~}'.
+If you try to tie together chords which have no common pitches, a
+warning message will appear and no ties will be created.
+
+@mudela[fragment,verbatim,center]
+ e' ~ e' <c' e' g'> ~ <c' e' g'>
+@end mudela
+
+
+
+[TODO: explain Requests]
+
+
+@cindex articulations
+
+@cindex scripts
+
+@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} and @file{script.scm}. 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 above notes, with the
+name of the corresponding symbol appearing underneath.
+
+@mudela[]
+
+ \score {
+ < \notes {
+ c''-\accent c''-\marcato c''-\staccatissimo c''-\fermata
+ c''-\stopped c''-\staccato c''-\tenuto c''-\upbow
+ c''-\downbow c''^\lheel c''-\rheel c''^\ltoe
+ c''-\rtoe c''-\turn c''-\open c''-\flageolet
+ c''-\reverseturn c''-\trill c''-\prall c''-\mordent
+ c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall
+ c''-\thumb c''-\segno c''-\coda
+ }
+ \context Lyrics \lyrics {
+ accent__ marcato__ staccatissimo__ fermata
+ stopped__ staccato__ tenuto__ upbow
+ downbow__ lheel__ rheel__ ltoe
+ rtoe__ turn__ open__ flageolet
+ reverseturn__ trill__ prall__ mordent
+ prallprall__ prallmordent__ uprall__ downprall
+ thumb__ segno__ coda
+ }
+ >
+ \paper {
+ linewidth = 5.875\in;
+ indent = 0.0;
+ }
+ }
+
+@end mudela
+
+In addition, it is possible to place arbitrary strings of text or
+TeX above or below notes by using a string instead of an
+identifier: `@code{c^"text"}'. Fingerings
+@cindex fingering
+ can be
+placed by simply using digits. All of these note ornaments appear in
+the printed output but have no effect on the MIDI rendering of the
+music.
+
+To save typing, fingering instructions (digits 0 to 9 are
+supported) and single characters shorthands exist for a few
+common symbols
+
+@mudela[]
+
+ \score {
+ \notes {
+ \property Voice.textStyle = typewriter
+ c''4-._"c-." s4
+ c''4--_"c-{}-" s4
+ c''4-+_"c-+" s4
+ c''4-|_"c-|" s4
+ c''4->_"c->" s4
+ c''4-^_"c-\\^{ }" s4
+ c''4-1_"c-1" s4
+ c''4-2_"c-2" s4
+ c''4-3_"c-3" s4
+ c''4-4_"c-4" s4
+ }
+ \paper {
+ linewidth = 5.875 \in;
+ indent = 0.0;
+ }
+ }
+
+@end mudela
+
+Dynamic marks are specified by using an identifier after a note:
+`@code{c4-\ff}' (the dash is optional for dynamics: `@code{c4 \ff})'.
+The available dynamic marks are:
+@code{\ppp}@keyindex{ppp},
+@code{\pp}@keyindex{pp}, @code{\p}@keyindex{p}, @code{\mp}@keyindex{mp},
+@code{\mf}@keyindex{mf}, @code{\f}@keyindex{f}, @code{\ff}@keyindex{ff},
+@code{\fff}@keyindex{fff}, @code{\fff}@keyindex{ffff},
+@code{\fp}@keyindex{fp}, @code{\sf}@keyindex{sf},
+@code{\sff}@keyindex{sff}, @code{\sp}@keyindex{sp},
+@code{\spp}@keyindex{spp}, @code{\sfz}@keyindex{sfz}, and
+@code{\rfz}@keyindex{rfz}.
+
+
+@example
+
+ \textscript@keyindex{textscript} @var{text} @var{style}
+@end example
+
+Defines a text to be printed over or under a note. @var{style} is a
+string that may be one of @code{roman}, @code{italic}, @code{typewriter},
+@code{bold}, @code{Large}, @code{large}, @code{dynamic} or @code{finger}.
+
+You can attach a general textscript request using this syntax:
+
+@quotation
+
+@example
+c4-\textscript "6" "finger"
+c4-\textscript "foo" "normal"
+@end example
+
+@end quotation
+
+This is equivalent to `@code{c4-6 c4-"foo"}'.
+
+
+@cindex scripts
+
+@example
+
+ \script@keyindex{script} @var{alias}
+@end example
+
+Prints a symbol above or below a note. The argument is a string
+which points into the script-alias table defined in @file{script.scm}.
+The scheme definitions specify whether the symbol follows notes into
+the staff, dependence of symbol placement on staff direction, and a
+priority for placing several symbols over one note. Usually the
+@code{\script}@keyindex{script} keyword is not used directly. Various
+helpful identifier definitions appear in @file{script.ly}.
+
+
+@cindex slur
+
+Slurs connects chords and try to avoid crossing stems. A slur is
+started with `@code{(}' and stopped with `@code{)}'. The
+starting `@code{(}' appears to the right of the first note in
+the slur. The terminal `@code{)}' appears to the left of the
+first note in the slur. This makes it possible to put a note in
+slurs from both sides:
+
+@mudela[fragment,verbatim,center]
+ f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
+@end mudela
+
+
+@cindex crescendo
+
+A crescendo mark is started with @code{\cr}@keyindex{cr} and terminated
+with @code{\rc}@keyindex{rc}. A decrescendo mark is started with
+@code{\decr}@keyindex{decr} and terminated with
+@code{\rced}@keyindex{rced}. There are also shorthands for these
+marks. A crescendo can be started with @code{\<}@keyindex{<} and a
+decrescendo can be started with @code{\>}@keyindex{>}. Either one can
+be terminated with @code{\!}@keyindex{"!}. Note that @code{\!}
+must go before the last note of the dynamic mark whereas @code{\rc}
+and @code{\rced} go after the last note. Because these marks are
+bound to notes, if you want to get several marks during one note, you
+must use spacer notes.
+
+@mudela[fragment,verbatim,center]
+ c'' \< \! c'' d'' \decr e'' \rced
+ < f''1 { s4 \< \! s2 \> \! s4 } >
+@end mudela
+
+
+@example
+
+ \spanrequest@keyindex{spanrequest} @var{startstop} @var{type}
+@end example
+
+Define a spanning request. The @var{startstop} parameter is either -1
+(@code{\start}@keyindex{start}) or 1 (@code{\stop}@keyindex{stop}) and
+@var{type} is a string that describes what should be started.
+Supported types are @code{crescendo}, @code{decrescendo},
+@code{beam}, @code{slur}. This is an internal command. Users should
+use the shorthands which are defined in the initialization file
+@file{spanners.ly}.
+
+You can attach a (general) span request to a note using
+
+@mudela[fragment,verbatim,center]
+ c'4-\spanrequest \start "slur"
+ c'4-\spanrequest \stop "slur"
+@end mudela
+
+The slur syntax with parentheses is a shorthand for this.
+
+
+
+@cindex tremolo marks
+
+@node tremolo, , , Reference Manual
+
+Tremolo marks can be printed on a single note by adding
+`@code{:}[@var{length}]' after the note. The length must be at
+least 8. A @var{length} value of 8 gives one line across
+the note stem. If the length is omitted, then the last value is
+used, or the value of the @code{abbrev}@indexcode{abbrev} property if there was
+no last value.
+
+@mudela[verbatim,fragment,center]
+ c'2:8 c':32
+@end mudela
+
+
+
+@node Compound music expressions, , , Reference Manual
+@section Compound music expressions
+
+@cindex compound music expressions
+
+@node compoundmusic, , , Reference Manual
+
+Music expressions are compound data structures. You can nest music
+expressions any way you like. This simple example shows how three
+chords can be expressed in two different ways:
+
+@mudela[fragment,verbatim,center]
+ \notes \context Staff {
+ \cadenza 1;
+ <a c'> <b d' > <c' e' >
+ <{a b c'}{c' d' e'}>
+ }
+@end mudela
+
+
+
+@cindex context selection
+
+@example
+
+ \context@keyindex{context}
+ @var{contexttype} [@code{=} @var{contextname}] @var{musicexpr}
+@end example
+
+Interpret @var{musicexpr} within a context of type @var{contexttype}.
+If the context does not exist, it will be created. The new context
+can optionally be given a name. See
+section XREF-contextselection [FIXME] and XREF-contextdefs [FIXME] for more
+information on interpretation contexts.
+
+
+
+@cindex input modes
+
+@cindex mode switch
+
+Mode switching keywords form compound music expressions: @code{\notes}
+@keyindex{notes} @var{musicexpr}, @code{\chords} @keyindex{chords}
+@var{musicexpr}, and @code{\lyrics} @keyindex{lyrics} @var{musicexpr}.
+These expressions do not add anything to the meaning of their
+arguments. They are just a way to indicate that the arguments should
+be parsed in indicated mode. See section XREF-modes [FIXME] for more
+information on modes.
+
+More information on context selection can be found in
+section XREF-contextselection [FIXME].
+
+
+
+@cindex sequential music
+
+
+
+@example
+
+ \sequential@keyindex{sequential}
+ @code{@{} @var{musicexprlist} @code{@}}
+@end example
+
+This means that list should be played or written in sequence, i.e.,
+the second after the first, the third after the second. The duration
+of sequential music is the the sum of the durations of the elements.
+There is a shorthand, which leaves out the keyword:
+
+@example
+
+ @code{@{} @var{musicexprlist} @code{@}}
+@end example
+
+
+
+@cindex simultaneous music
+
+@indexcode{<}
+@indexcode{>}
+
+@example
+
+ \simultaneous@keyindex{simultaneous}
+ @code{@{} @var{musicexprlist} @code{@}}
+@end example
+
+It constructs a music expression where all of its arguments start at
+the same moment. The duration is the maximum of the durations of the
+elements. The following shorthand is a common idiom:
+
+@example
+
+ @code{<} @var{musicexprlist} @code{>}
+@end example
+
+If you try to use a chord as the first thing in your score, you might
+get multiple staffs instead of a chord.
+
+@mudela[verbatim,center]
+ \score {
+ \notes <c''4 e''>
+ \paper {
+ linewidth = -1.;
+ }
+ }
+@end mudela
+
+This happens because the chord is interpreted by a score context.
+Each time a note is encountered a default Voice context (along with a
+Staff context) is created. The solution is to explicitly instantiate
+a Voice context:
+
+@mudela[verbatim,center]
+ \score {
+ \notes\context Voice <c''4 e''>
+ \paper {
+ linewidth = -1.;
+ }
+ }
+@end mudela
+
+
+
+@cindex relative pitch specification
+
+@node relative, , , Reference Manual
+
+It is easy to get confused by octave changing marks and accidentally
+putting a pitch in the wrong octave. A much better way of entering a
+note's octave is `the relative octave' mode.
+
+@example
+
+ \relative@keyindex{relative} @var{startpitch} @var{musicexpr}
+@end example
+
+The octave of notes that appear in @var{musicexpr} are calculated as
+follows: If no octave changing marks are used, the basic interval
+between this and the last note is always taken to be a fourth or
+less.@footnote{The interval is determined without regarding
+accidentals. A @code{fisis} following a @code{ceses} will be put above
+the @code{ceses}.} The octave changing marks `@code{'}' and `@code{,}'
+can then be added to raise or lower the pitch by an extra octave.
+Upon entering relative mode, an absolute starting pitch must be
+specified that will act as the predecessor of the first note of
+@var{musicexpr}.
+
+Entering scales is straightforward in relative mode.
+
+@mudela[fragment,verbatim,center]
+ \relative c' {
+ c d e f g a b c c,
+ }
+@end mudela
+
+And octave changing marks are used for intervals greater than a fourth.
+
+@mudela[fragment,verbatim,center]
+ \relative c'' {
+ c g c f, c' a, e'' }
+@end mudela
+
+If the preceding item is a chord, the first note of the chord is used
+to determine the first note of the next chord. But other notes
+within the second chord are determined by looking at the immediately
+preceding note.
+
+@mudela[fragment,verbatim,center]
+ \relative c' {
+ c <c e g>
+ <c' e g>
+ <c, e' g>
+ }
+@end mudela
+
+The pitch after the @code{\relative} contains a notename. To parse
+the pitch as a notename, you have to be in note mode, so there must
+be a surrounding @code{\notes}@keyindex{notes} keyword (which is not
+shown here).
+
+The relative conversion will not affect @code{\transpose} or
+@code{\relative} sections in its argument. If you want to use
+relative within transposed music, you must place an additional
+@code{\relative} inside the @code{\transpose}.
+
+It is strongly recommended to use relative pitch mode: less work,
+less error-prone, and more readable.
+
+
+
+Chord names are a way to generate simultaneous music expressions that
+correspond with traditional chord names. It can only be used in
+Chord mode (see section XREF-modes [FIXME]).
+
+@example
+
+ @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}].
+@end example
+
+@var{tonic} should be the tonic note of the chord, and @var{duration}
+is the chord duration in the usual notation. There are two kinds of
+modifiers. One type is @emph{chord additions}, which are obtained by
+listing intervals separated by dots. An interval is written by its
+number with an optional `@code{+}' or `@code{-}' to indicate raising or
+lowering by half a step. Chord additions has two effects: It adds
+the specified interval and all lower odd numbered intervals to the
+chord, and it may lower or raise the specified interval. Intervals
+must be separated by a dot (`@code{.}').
+
+@quotation
+
+@mudela[fragment,verbatim]
+\transpose c'' {
+ \chords {
+ c1 c-3- c-7 c-8
+ c-9 c-9-.5+.7+ c-3-.5- c-4.6.8
+ }
+}
+
+@end mudela
+@end quotation
+
+The second type of modifier that may appear after the `@code{-}' is a
+named modifier. Named modifiers are listed in the file
+@file{chord-modifiers.ly}. The available modifiers are `@code{m}' and
+`@code{min}' which lower the 3rd half a step, `@code{aug}@indexcode{aug}' which
+raises the 5th, `@code{dim}@indexcode{dim}' which lowers the 5th,
+`@code{maj}@indexcode{maj}' which adds a raised 7th, and `@code{sus}@indexcode{sus}'
+which replaces the 5th with a 4th.
+
+@quotation
+
+@mudela[fragment,verbatim]
+\transpose c'' {
+ \chords {
+ c1-m c-min7 c-maj c-aug c-dim c-sus
+ }
+}
+
+@end mudela
+@end quotation
+
+
+Chord subtractions are used to eliminate notes from a chord. The
+notes to be subtracted are listed after a `@code{^}' character,
+separated by dots.
+
+@mudela[fragment,verbatim,center]
+ \transpose c'' {
+ \chords {
+ c1^3 c-7^5.3 c-8^7
+ }
+ }
+@end mudela
+
+Chord inversions can be specified by appending `@code{/}@indexcode{/}' and
+the name of a single note to a chord. This has the effect of
+lowering the specified note by an octave so it becomes the lowest
+note in the chord. If the specified note is not in the chord, a
+warning will be printed.
+
+@mudela[fragment,verbatim,center]
+ \transpose c''' {
+ \chords {
+ c1 c/e c/g c-7/e
+ }
+ }
+
+@end mudela
+
+Throughout these examples, chords have been shifted around the staff
+using @code{\transpose}.
+
+You should not combine @code{\relative} with named chords.
+
+
+
+@cindex tuplets
+
+Tuplets are made out of a music expression by multiplying their
+duration with a fraction.
+
+@example
+
+ \times@keyindex{times} @var{fraction} @var{musicexpr}
+@end example
+
+The duration of @var{musicexpr} will be multiplied by the fraction.
+In print, the fraction's denominator will be printed over the notes,
+optionally with a bracket. The most common tuplet is the triplet in
+which 3 notes have the length of 2, so the notes are 2/3 of
+their written length:
+
+@mudela[fragment,verbatim,center]
+ g'4 \times 2/3 {c'4 c' c'} d'4 d'4
+@end mudela
+
+
+
+@cindex grace notes
+
+@example
+
+ \grace@keyindex{grace} @var{musicexpr}
+@end example
+
+A grace note expression has duration 0; the next real note is
+assumed to be the main note.
+
+You cannot have the grace note after the main note, in terms of
+duration, and main notes, but you can typeset the grace notes to the
+right of the main note using the property
+@code{graceAlignPosition}@indexcode{graceAlignPosition}.
+
+When grace music is interpreted, a score-within-a-score is set up:
+@var{musicexpr} has its own time bookkeeping, and you could (for
+example) have a separate time signature within grace notes. While in
+this score-within-a-score, you can create notes, beams, slurs, etc.
+Unbeamed eighth notes and shorter by default have a slash through the
+stem. This behavior can be controlled with the
+@code{stemStyle}@indexcode{stemStyle} property.
+
+@quotation
+
+@mudela[fragment,verbatim]
+\relative c'' {
+ \grace c8 c4 \grace { [c16 c16] } c4
+ \grace { \property Grace.stemStyle = "" c16 } c4
+}
+
+@end mudela
+@end quotation
+
+At present, nesting @code{\grace}@keyindex{grace} notes, e.g.
+
+@example
+
+ @code{\grace @{ \grace c32 c16 @} c4}
+@end example
+
+may result in run-time errors of LilyPond. Since the meaning of such
+a construct is unclear, we don't consider this a loss. Similarly,
+juxtaposing two @code{\grace} sections is syntactically valid, but
+makes no sense and may cause runtime errors.
+
+Ending a staff or score with grace notes may also generate a run-time
+error, since there will be no main note to attach the grace notes to.
+
+
+
+@cindex repeats
+
+@node sec-repeats, , , Reference Manual
+
+In order to specify repeats, use the @code{\repeat}@keyindex{repeat}
+keyword. Since repeats look and sound differently when played or
+printed, there are a few different variants of repeats.
+
+@table @samp
+ @item unfolded
+ Repeated music is fully written (played) out. Useful for MIDI
+ output.
+
+ @item volta
+ This is the normal notation: Repeats are not written out, but
+ alternative endings (voltas) are printed, left to right.
+
+ @item folded
+ Alternative endings are written stacked, which is useful for
+ lyrics.
+@end table
+
+The syntax for repeats is
+
+@example
+
+ \repeat @var{variant} @var{repeatcount} @var{repeatbody}
+@end example
+
+If you have alternative endings, you may add
+
+@example
+
+ \alternative@keyindex{alternative}
+ @code{@{} @var{alternative1}
+ @var{alternative2}
+ @var{alternative3} @dots{} @code{@}}
+@end example
+
+where each @var{alternative} is a Music expression.
+
+Normal notation repeats are used like this:
+
+@quotation
+
+@mudela[fragment,verbatim]
+ c'1
+ \repeat volta 2 { c'4 d' e' f' }
+ \repeat volta 2 { f' e' d' c' }
+
+@end mudela
+@end quotation
+
+With alternative endings:
+
+@quotation
+
+@mudela[fragment,verbatim]
+ c'1
+ \repeat volta 2 {c'4 d' e' f'}
+ \alternative { {d'2 d'} {f' f} }
+
+@end mudela
+@end quotation
+
+Folded repeats look like this:@footnote{Folded repeats offer little
+more over simultaneous music. However, it is to be expected that
+more functionality -- especially for the MIDI backend -- will be
+implemented.}
+
+@quotation
+
+@mudela[fragment,verbatim]
+ c'1
+ \repeat fold 2 {c'4 d' e' f'}
+ \alternative { {d'2 d'} {f' f} }
+
+@end mudela
+@end quotation
+
+@quotation
+
+@mudela[fragment,verbatim]
+\context Staff {
+ \relative c' {
+ \partial 4;
+ \repeat volta 2 { e | c2 d2 | e2 f2 | }
+ \alternative { { g4 g g } { a | a a a a | b1 } }
+ }
+}
+
+@end mudela
+@end quotation
+
+If you don't give enough alternatives for all of the repeats, then
+the first alternative is assumed to be repeated often enough to equal
+the specified number of repeats.
+
+@quotation
+
+@mudela[fragment,verbatim]
+\context Staff {
+ \relative c' {
+ \repeat volta 3 { \partial 4; e | c2 d2 | e2 f2 | }
+ \alternative { { g4 g g }
+ {\partial 1; e4 e e }
+ {\partial 1; a a a a | b1 } }
+ }
+}
+
+@end mudela
+@end quotation
+
+It is possible to nest @code{\repeat}. This is not entirely
+supported: the notes will come be in the right places, but the repeat
+bars will not.
+
+
+
+@cindex transposition of pitches
+
+@node transpose, , , Reference Manual
+
+A music expression can be transposed with
+@code{\transpose}@keyindex{transpose}. The syntax is
+
+@example
+
+ \transpose @var{pitch} @var{musicexpr}
+@end example
+
+This means that middle C in @var{musicexpr} is transposed to
+@var{pitch}.
+
+@code{\transpose} distinguishes between enharmonic pitches: both
+@code{\transpose cis'} or @code{\transpose des'} will transpose up half
+a tone. The first version will print sharps and the second version
+will print flats.
+
+@quotation
+
+@mudela[fragment,verbatim]
+\context Staff {
+ \clef "F";
+ { \key e; c d e f }
+ \clef "G";
+ \transpose des'' { \key e; c d e f }
+ \transpose cis'' { \key e; c d e f }
+}
+
+@end mudela
+@end quotation
+
+If you want to use both @code{\transpose} and @code{\relative}, then
+you must use @code{\transpose} first. @code{\relative} will have no
+effect music that appears inside a @code{\transpose}.
+
+
+
+@cindex automatic lyric durations
+
+If you have lyrics that are set to a melody, you can import the
+rhythm of that melody into the lyrics using @code{\addlyrics}.
+@keyindex{addlyrics} The syntax for this is
+
+@example
+
+ \addlyrics @var{musicexpr1 musicexpr2}
+@end example
+
+This means that both @var{musicexpr1} and @var{musicexpr2} are
+interpreted, but that every non-command atomic music expression
+(``every syllable'') in @var{musicexpr2} is interpreted using timing
+of @var{musicexpr1}.
+
+If the property @code{automaticMelismata}@indexcode{automaticMelismata} is set in the
+context of @var{musicexpr1}, no lyrics will be put on slurred or tied
+notes.
+
+@quotation
+
+@mudela[verbatim,fragment]
+\addlyrics
+\transpose c'' {
+ \property Voice.automaticMelismata = "1"
+ c8 () cis d8. e16 f2
+}
+\context Lyrics \lyrics {
+ do4 re mi fa }
+
+@end mudela
+@end quotation
+
+You should use a single rhythm melody, and single rhythm lyrics (a
+constant duration is the obvious choice). If you do not, you will get
+undesired effects when using multiple stanzas:
+
+@quotation
+
+@mudela[verbatim,fragment]
+\addlyrics
+\transpose c'' {
+ c8 () cis d8. e16 f2
+}
+\context Lyrics \lyrics
+< { do4 re mi fa }
+ { do8 re mi fa } >
+
+@end mudela
+@end quotation
+
+It is valid (but probably not very useful) to use notes instead of
+lyrics for @var{musicexpr2}.
+
+
+
+
+@node Ambiguities, , , Reference Manual
+@section Ambiguities
+
+@cindex ambiguities
+
+The grammar contains a number of ambiguities.@footnote{The authors
+hope to resolve them at a later time.}
+
+@itemize @bullet
+ @item The assignment
+
+ @example
+foo = bar
+@end example
+
+ can be interpreted as making a string identifier @code{\foo}
+ containing @code{"bar"}, or a music identifier @code{\foo}
+ containing the syllable `bar'.
+
+ @item The assignment
+
+ @example
+foo = -6
+@end example
+
+ can be interpreted as making an integer identifier
+ containing -6, or a Request identifier containing the
+ fingering `6' (with neutral direction).
+
+ @item If you do a nested repeat like
+
+ @quotation
+
+@example
+\repeat @dots{}
+\repeat @dots{}
+\alternative
+@end example
+
+ @end quotation
+
+ then it is ambiguous to which @code{\repeat} the
+ @code{\alternative} belongs. This is the classic if-then-else
+ dilemma. It may be solved by using braces.
+
+ @item (an as yet unidentified ambiguity :-)
+@end itemize
+
+
+
+@node Notation conversion specifics, , , Reference Manual
+@section Notation conversion specifics
+
+
+
+@cindex automatic beam generation
+
+@node autobeam, , , Reference Manual
+
+By default, LilyPond will generate beams automatically. This feature
+can be disabled by setting the @code{Voice.noAutoBeaming}@indexcode{Voice.noAutoBeaming}
+property to 1. It can be overridden for specific cases by
+specifying explicit beams as described in
+section XREF-manualbeam [FIXME].
+
+A large number of Voice properties are used to decide how to generate
+beams. Their default values appear in @file{auto-beam-settings.ly}.
+In general, beams can begin anywhere, but their ending location is
+significant. Beams can end on a beat, or at durations specified by
+the @code{Voice.beamAutoEnd}@indexcode{Voice.beamAutoEnd} property. To end beams every
+quarter note, for example, you could set
+@code{Voice.beamAutoEnd}@indexcode{Voice.beamAutoEnd} equal to `@code{"1/4"}'. To end beams
+at every three eighth notes you would set it to `@code{"3/8"}'. The
+same syntax can be used to specify beam starting points using
+@code{Voice.beamAutoBegin}@indexcode{Voice.beamAutoBegin}.
+
+To allow different settings for different time signatures, these
+property names can start with `@code{time}@var{N}@code{_}@var{M}' to
+restrict the definition to `@var{N}@code{/}@var{M}' time. For example,
+to specify beams ending only for 6/8 time you would use the
+property @code{Voice.time6_8beamAutoEnd}. To allow different endings
+for notes of different durations, the duration can be tacked onto the
+end of the property. To specify beam endings for beams that contain
+32nd notes, you would use @code{Voice.beamAutoEnd_32}.
+
+
+
+@cindex chord names
+
+@cindex chords
+
+@cindex printing!chord names
+
+For displaying printed chord names, use the @code{ChordNames}@indexcode{ChordNames}
+and @code{ChordNameVoice}@indexcode{ChordNameVoice} contexts. The chords may be entered
+either using the notation described above, or directly using
+simultaneous music.
+
+@quotation
+
+@mudela[fragment,verbatim]
+<
+ \context ChordNames {
+ \chords{a b c} \notes{<d f g> <e g b>}
+ }
+ \context Staff \notes {
+ a b c' d' e'
+ }
+>
+
+@end mudela
+@end quotation
+
+LilyPond examines chords specified as lists of notes to determine a
+name to give the chord. By default, LilyPond will not try to
+identify chord inversions:
+
+@mudela[fragment,verbatim,center]
+ <
+ \context ChordNameVoice \notes {
+ <e'1 g' c''>
+ }
+ \context Thread \notes {
+ <e'1 g' c''>
+ }
+ >
+@end mudela
+
+If you want inversions to be recognized, you must set the property
+@code{ChordNames.chordInversion}@indexcode{ChordNames.chordInversion}:
+
+@mudela[fragment,verbatim,center]
+ <
+ \property Score.chordInversion = 1
+ \context ChordNameVoice \notes {
+ <e'1 g' c''>
+ }
+ \context Thread \notes {
+ <e'1 g' c''>
+ }
+ >
+@end mudela
+
+
+
+@cindex lyrics
+
+@cindex printing!lyrics
+
+@node lyricprint, , , Reference Manual
+
+Lyric syllables must be interpreted within a @code{Lyrics} context
+
+@cindex context!Lyrics
+ for printing them.
+
+Here is a full example:
+
+@quotation
+
+@mudela[verbatim]
+\score {
+ <
+ \notes \transpose c'' {
+ c d e c | c d e c |
+ e f g2 | e4 f g2 \bar "|.";
+ }
+ \context Lyrics \lyrics {
+ Va-4 der Ja- cob Va- der Ja- cob
+ Slaapt gij nog?2 Slaapt4 gij nog?2
+ }
+ >
+}
+
+@end mudela
+@end quotation
+
+You may want a continuous line after the syllables to show melismata.
+To achieve this effect, add a `@code{__}' lyric as a separate word
+after the lyric to be extended. This will create an extender, a line
+that extends over the entire duration of the lyric. This line will
+run all the way to the start of the next lyric, so you may want to
+shorten it by using a blank lyric (using `@code{_}').
+
+@quotation
+
+@mudela[verbatim]
+\score {
+ <
+ \notes \relative c'' {
+ a4 () b () c () d | c () d () b () a | c () d () b () a
+ }
+ \context Lyrics \lyrics {
+ foo1 __ | bar2. __ _4 | baz1 __
+ }
+ >
+}
+
+@end mudela
+@end quotation
+
+
+If you want to have hyphens centered between syllables (rather than
+attached to the end of the first syllable) you can use the special
+`@code{-}@code{-}' lyric as a separate word between syllables. This
+will result in a hyphen which length varies depending on the space
+between syllables, and which will be centered between the syllables.
+For example:
+
+@quotation
+
+@mudela[verbatim]
+\score {
+ <
+ \notes \transpose c'' {
+ c d e c | c d e c |
+ e f g2 | e4 f g2 \bar "|.";
+ }
+ \context Lyrics \lyrics {
+ Va4 -- der Ja -- cob | Va -- der Ja -- cob |
+ Slaapt gij nog?2 | Slaapt4 gij nog?2
+ }
+ >
+}
+
+@end mudela
+@end quotation
+
+
+
+@node Notation Contexts, , , Reference Manual
+@section Notation Contexts
+
+@cindex notation contexts
+
+Notation contexts are objects that only exist during a run of
+LilyPond. During the interpretation phase of LilyPond, the Music
+expression contained in a @code{\score} block is interpreted in time
+order. This is the order in which humans read, play, and write
+music.
+
+A context is an object that holds the reading state of the
+expression; it contains information like
+
+@itemize @bullet
+ @item What notes are playing at this point?
+ @item What symbols will be printed at this point?
+ @item In what style will they printed?
+ @item What is the current key signature, time signature, point within
+ the measure, etc.?
+@end itemize
+
+Contexts are grouped hierarchically: A @code{Voice} context is
+contained in a @code{Staff} context (because a staff can contain
+multiple voices at any point), a @code{Staff} context is contained in
+a @code{Score}, @code{StaffGroup}, or @code{ChoirStaff} context (because
+these can all contain multiple staffs).
+
+Contexts associated with sheet music output are called @emph{notation
+contexts}, those for sound output are called playing contexts.
+
+Contexts are created either manually or automatically. Initially,
+the top level music expression is interpreted by the top level
+context (the @code{Score} context). When a atomic music expression
+(i.e. a note, a rest, @code{\bar}, or @code{\time} commands), a nested
+set of contexts is created that can process these atomic expressions,
+as in this example:
+
+@example
+
+ @example
+\score @{ \notes < c4 > @}
+@end example
+
+@end example
+
+The sequential music, `@code{@{ c4 @}}' is interpreted by @code{Score}
+context. When the note `@code{c4}' itself is interpreted, a set of
+contexts is needed that will accept notes. The default for this is a
+@code{Voice} context, contained in a @code{Staff} context. Creation of
+these contexts results in the staff being printed.
+
+
+@node contextselection, , , Reference Manual
+
+@cindex context
+
+You can also create contexts manually, and you probably have to do so
+if you want to typeset complicated multiple part material. If a
+`@code{\context} @var{name} @var{musicexpr}' expression is encountered
+during the interpretation phase, the @var{musicexpr} argument will be
+interpreted with a context of type @var{name}. If you specify a name,
+the specific context with that name is searched.
+
+If a context of the specified type and name can not be found, a new
+one is created. For example,
+
+@quotation
+
+@mudela[verbatim]
+\score {
+ \notes \relative c'' {
+ c4 <d4 \context Staff = "another" e4> f
+ }
+}
+
+@end mudela
+@end quotation
+
+In this example, the @code{c} and @code{d} are printed on the
+default staff. For the @code{e}, a context Staff called
+`@code{another}' is specified; since that does not exist, a new
+context is created. Within @code{another}, a (default) Voice context
+is created for the @code{e4}. When all music referring to a
+context is finished, the context is ended as well. So after the
+third quarter, @code{another} is removed.
+
+Almost all music expressions inherit their interpretation context
+from their parent. In other words, suppose that the syntax for a
+music expression is
+
+@example
+
+ \keyword @var{musicexpr1} @var{musicexpr2} @dots{}
+@end example
+
+When the interpretation of this music expression starts, the context
+for @var{musicexpr1}, @var{musicexpr2}, etc. is that of the total
+expression.
+
+Lastly, you may wonder, why this:
+
+@quotation
+
+@example
+\score @{
+ \notes \relative c'' @{
+ c4 d4 e4
+ @}
+@}
+@end example
+
+@end quotation
+
+doesn't result in this:
+
+@mudela[]
+
+ \score {
+ \notes \relative c'' {
+ <c4> <d4> <e4>
+ }
+ }
+
+@end mudela
+
+For the @code{c4}, a default @code{Staff} (with a contained
+@code{Voice}) context is created. After the @code{c4} ends, no
+music refers to this default staff, so it would be ended, with the
+result shown. To prevent this inconvenient behavior, the context to
+which the sequential music refers is adjusted during the
+interpretation. So after the @code{c4} ends, the context of the
+sequential music is also the default @code{Voice} context.
+The @code{d4} gets interpreted in the same context
+as @code{c4}.
+
+
+
+These are the contexts supplied with the package. They are defined
+in the initialization file @file{ly/engraver.ly}.
+
+@table @samp
+ @item @code{Grace}@indexcode{Grace}
+ The context for handling grace notes. It is instantiated
+ automatically when you use @code{\grace}. Basically, it is an
+ `embedded' miniature of the Score context. Since this context
+ needs special interaction with the rest of LilyPond, you should
+ not explicitly instantiate it.
+
+ @item @code{LyricVoice}@indexcode{LyricVoice}
+ Corresponds to a voice with lyrics. Handles the printing of a
+ single line of lyrics.
+
+ @item @code{Thread}@indexcode{Thread}
+ Handles note heads, and is contained in the Voice context. You
+ have to instantiate this explicitly if you want to adjust the
+ style of individual note heads.
+
+ @item @code{Voice}@indexcode{Voice}
+ Corresponds to a voice on a staff. This context handles the
+ conversion of dynamic signs, stems, beams, super- and subscripts,
+ slurs, ties, and rests.
+
+ You have to instantiate this explicitly if you want to have
+ multiple voices on the same staff.
+
+ @item @code{ChordNamesVoice}@indexcode{ChordNamesVoice}
+ A voice with chord names. Handles printing of a line of chord
+ names.
+
+ @item @code{ChordNames}@indexcode{ChordNames}
+ Typesets chord names. Can contain @code{ChordNamesVoice}
+ contexts.
+
+ @item @code{Lyrics}@indexcode{Lyrics}
+ Typesets lyrics. It can contain @code{LyricVoice} contexts.
+
+ @item @code{Staff}@indexcode{Staff}
+ Handles clefs, bar lines, keys, accidentals. It can contain
+ @code{Voice} contexts.
+
+ @item @code{RhythmicStaff}@indexcode{RhythmicStaff}
+ A context like @code{Staff} but for printing rhythms. Pitches are
+ ignored; the notes are printed on one line. It can contain
+ @code{Voice} contexts.
+
+ @item @code{GrandStaff}@indexcode{GrandStaff}
+ Contains @code{Staff} or @code{RhythmicStaff} contexts. It adds a
+ brace on the left side, grouping the staffs together. The bar
+ lines of the contained staffs are connected vertically. It can
+ contain @code{Staff} contexts.
+
+ @item @code{PianoStaff}@indexcode{PianoStaff}
+ Just like @code{GrandStaff} but with @code{minVerticalAlign} set
+ equal to @code{maxVerticalAlign} so that interstaff beaming and
+ slurring can be used.
+
+ @item @code{StaffGroup}@indexcode{StaffGroup}
+ Contains @code{Staff} or @code{RhythmicStaff} contexts. Adds a
+ bracket on the left side, grouping the staffs together. The bar
+ lines of the contained staffs are connected vertically. It can
+ contain @code{Staff}, @code{RhythmicStaff}, @code{GrandStaff}, or
+ @code{Lyrics} contexts.
+
+ @item @code{ChoirStaff}@indexcode{ChoirStaff}
+ Identical to @code{StaffGroup} except that the contained staffs
+ are not connected vertically.
+
+ @item @code{Score}@indexcode{Score}
+ This is the top level notation context. No other context can
+ contain a @code{Score} context. This context handles the
+ administration of time signatures. It also makes sure that items
+ such as clefs, time signatures, and key-signatures are aligned
+ across staffs. It can contain @code{Lyrics}, @code{Staff},
+ @code{RhythmicStaff}, @code{GrandStaff}, @code{StaffGroup}, and
+ @code{ChoirStaff} contexts.
+
+ You cannot explicitly instantiate a Score context (since it is
+ not contained in any other context). It is instantiated
+ automatically when an output definition (a @code{\score} or
+ @code{\paper} block) is processed.
+@end table
+
+
+
+Properties that are set in one context are inherited by all of the
+contained contexts. This means that a property valid for the
+@code{Voice} context can be set in the @code{Score} context (for
+example) and thus take effect in all @code{Voice} contexts.
+
+Properties can be preset within the @code{\translator} block
+corresponding to the appropriate context. In this case, the syntax
+is
+
+@example
+
+ @var{propname} @code{=} @var{value}
+@end example
+
+This assignment happens before interpretation starts, so a
+@code{\property} expression will override any predefined settings.
+
+The @code{\property} expression will create any property you specify.
+There is no guarantee that a property will be used. So if you spell
+a property name wrong, there will be no error message.
+
+The property settings are used during the interpretation phase. They
+are read by the LilyPond modules where interpretation contexts are
+built of. These modules are called @emph{translators}. Translators for
+notation are called @emph{engravers}, and translators for sound are
+called @emph{performers}.
+
+The precise result of a property is determined by the implementation
+of the translator that reads them. Therefore, the result of a
+property can vary, since it is implementation and configuration
+dependent.
+
+In order to fully find out what properties are used, you must
+currently search the source code for calls to @code{get_property}.
+The rest of the section is devoted to an (incomplete) overview of
+available properties.
+
+
+@cindex properties!Lyrics
+
+@table @samp
+ @item @code{textStyle}@indexcode{textStyle}
+ Set the font for lyrics. The available font choices are
+ @code{roman}, @code{italic}, @code{bold}, @code{large}, @code{Large},
+ @code{typewriter}, and @code{finger}. The @code{finger} font can
+ only display numbers. Note also that you must be careful when
+ using @code{\property} in Lyrics mode, because of the way strings
+ are parsed. Either put quotes around the arguments to
+ @code{\property} or be sure to leave a space on both sides of the
+ dot.
+@end table
+
+
+@cindex properties!Thread
+
+@table @samp
+ @item @code{noteheadStyle}@indexcode{noteheadStyle}
+ Selects type of note head. Choices are @code{cross},
+ @code{diamond}, @code{harmonic}, @code{transparent}, and @code{""}.
+ They are shown in that order below.
+
+ @mudela[center]
+
+ \score {
+ \notes {
+ \property Staff.barNonAuto = 1
+ \property Voice.noteHeadStyle = cross
+ a'
+ \property Voice.noteHeadStyle = diamond
+ a'
+ \property Voice.noteHeadStyle = harmonic
+ a'
+ \property Voice.noteHeadStyle = transparent
+ a'
+ \property Voice.noteHeadStyle = ""
+ a'
+ }
+ \paper {
+ linewidth = -1.;
+ }
+ }
+
+@end mudela
+@end table
+
+@subsubheading Grace properties
+
+@cindex properties!Grace
+
+
+@table @samp
+ @item @code{stemStyle}@indexcode{stemStyle}
+ By default set to @code{"grace"} meaning that all unbeamed
+ notes with flags are typeset with a slash through the flag.
+ Setting to @code{""} gives standard flags.
+@end table
+
+
+@subsubheading Voice properties
+
+@cindex properties!Voice
+
+@table @samp
+ @item @code{abbrev}@indexcode{abbrev}
+ Set length for tremolo to be used if no length is explicitly
+ specified.
+
+ @item @code{articulationScriptPadding}@indexcode{articulationScriptPadding}
+
+ Determines the extra space added between articulation marks, such
+ as staccato, tenuto, trill, up/down bow or fermata, and the
+ closest staff line or note.
+
+ @item @code{articulationScriptVerticalDirection}
+ @indexcode{articulationScriptVerticalDirection}
+ Determines the location of articulation marks. Set to @code{\up}
+ to print marks above the staff; set to @code{\down} to print marks
+ below the staff. This property does not override explicit
+ directions marked with `@code{^}' or `@code{_}' in the mudela file.
+
+ @item @code{noAutoBeaming}@indexcode{beamAuto}
+ If set to 1 then beams are not generated automatically.
+
+ @item @code{beamAutoEnd}@indexcode{beamAutoEnd}
+ Specifies when automatically generated beams can end. See
+ section XREF-autobeam [FIXME].
+
+ @item @code{beamAutoBegin}@indexcode{beamAutoBegin}
+ Specifies when automatically generated beams can start. See
+ section XREF-autobeam [FIXME].
+
+ @item @code{beamquantisation}@indexcode{beamquantisation}
+ Set to @code{\none} for no quantization. Set to @code{\normal} to
+ quantize position and slope. Set to @code{\traditional} to avoid
+ wedges. These three settings are available via
+ @code{\beamposfree}@keyindex{beamposfree},
+ @code{\beamposnormal}@keyindex{beamposnormal}, and
+ @code{\beampostraditional}@keyindex{beampostraditional}.
+
+ @item @code{beamslopedamping}@indexcode{beamslopedamping}
+ Set to @code{\none} for undamped beams. Set to @code{\normal} for
+ damped beams. Set to @code{\infinity} for beams with zero slope.
+ The identifiers
+ @code{\beamslopeproportional}@keyindex{beamslopeproportional},
+ @code{\beamslopedamped}@keyindex{beamslopedamped}, and
+ @code{\beamslopezero}@keyindex{beamslopezero} each set the
+ corresponding value.
+
+ @item @code{dynamicDirection}@indexcode{dynamicDirection}
+ Determines location of dynamic marks. Set to @code{\up} to print
+ marks above the staff; set to @code{\down} to print marks below
+ the staff.
+
+ @item @code{dynamicStyle}@indexcode{dynamicStyle}
+ Set the text style for dynamics.
+
+ @item @code{fontSize}@indexcode{fontSize}
+ Can be used to select smaller font sizes for music. The normal
+ font size is 0, and the two smaller sizes are -1
+ and -2.
+
+ @item @code{forceHorizontalShift}@indexcode{forceHorizontalShift}
+ Force horizontal shift for collision resolution. It overrides
+ automatic collision resolution. The value is the shift amount
+ expressed in @code{note_width}, as set in the paper section.
+
+[FIXME: this should be moved]
+
+Lilypond always arranges note heads on alternate sides of a stem (that
+is, within a single voice) as necessary to prevent collisions (note head
+overlaps). For up stems, the upper note of a colliding pair is placed
+on the right side of the stem, the lower on the left. For down stems,
+the algorithm works in reverse.
+
+Lily also attempts to prevent collisions of note heads in different
+voices. A situation where chords of two or more voices are played
+simultaneously within one staff.
+
+By default, if only two voices (and both have opposite stem directions)
+are in this 'collision group', the notes both are shifted by @code{0.5
+\quartwidth} if there are unisons or seconds between the voices.
+
+If there are more than two voices in a collision group, shifting is
+inactive by default, since in this case, there are multiple chords with
+the same stem direction. By distinguish between those chords, LilyPond
+can do collision resolution in these cases as well.
+
+Distinguishing between voices with the same stem direction, is done by
+setting the property @code{Voice.horizontalNoteShift}. It must be set
+to a different integer for each voice. Then, all note heads in collision
+groups (not just unisons and seconds) will be offset, one voice relative
+another. The following fragment of sheet music shows how shifting is
+done, with values of @code{horizontalNoteShift} printed over and under
+the notes. In this case the chords are just simple notes.
+
+@c URG : mudela book bug.
+@mudela[singleline]
+\score {
+ \notes \context Staff <
+ \context Voice = VA { \stemup f''4^"0" }
+ \context Voice = VB {\stemup
+ \property Voice.horizontalNoteShift = 1 d''4^" 1" }
+ \context Voice = VC { \stemup \property
+Voice.horizontalNoteShift = 2 b'4^" 2" }
+ \context Voice = VD { \stemdown \property
+Voice.horizontalNoteShift = 1 g'4_"1 " }
+ \context Voice = VE { \stemdown e'4_"0" }
+ >
+}
+@end mudela
+
+If you are not satisfied with the collision resolution of LilyPond, you
+can override the horizontal shift value of the chord of one Voice, by
+setting @code{forceHorizontalShift}. This sets the amount shift,
+measured in black note head widths.
+
+To take complete control of note position shifts in complex passages,
+you have set things up for normal collisions and override all shifts by
+setting @code{forceHorizontalShift} to zero everywhere
+@example
+\property Voice.horizontalNoteShift = <n>
+\property Voice.forceHorizontalShift = "0.0"
+@end example
+
+Then you can set the force property to a suitable value before each note
+that really needs it (unisons and seconds), and reset it to 0.0 after
+the note.
+
+ @item @code{horizontalNoteShift}@indexcode{horizontalNoteShift}
+ Enable LilyPond to shift notes horizontally if they collide with
+ other notes. This is useful when typesetting many voices on one
+ staff. The identifier @code{\shift}@keyindex{shift} is defined to
+ enable this. Traditionally, the outer chords (the upmost and
+ downmost voices), should have no @code{horizontalNoteShift}.
+
+ @item @code{markScriptPadding}@indexcode{markScriptPadding}
+ Determines the extra space added between the mark and the closest
+ staff line or note.
+
+ @item @code{markDirection}@indexcode{markDirection}
+ Determines if marks should be printed above or below the staff.
+ Set to @code{\up} to print marks above the staff; set to
+ @code{\down} to print marks below the staff.
+
+ @item @code{midiInstrument}@indexcode{midiInstrument}
+ Sets the instrument for MIDI output. If this property is not set
+ then LilyPond will use the @code{instrument} property. This must
+ be set to one of the strings on the list of MIDI instruments that
+ appears in section XREF-midilist [FIXME]. If you use a string which
+ is not listed, LilyPond will silently substitute piano.
+
+ @item @code{oldTieBehavior}@indexcode{oldTieBehavior}
+ Set to 1 in order to get old tie behavior where ties would
+ connect unequal pitches. This property is deprecated, and its
+ use is not recommended.
+
+ @item @code{restStyle}@indexcode{restStyle}
+ Change the layout of rests shorter than quarter notes.
+ Currently, the standard layout @code{""} and mensural notation
+ @code{"mensural"} are available. Mensural rests of duration
+ 32 or shorter are not available.
+
+ @item @code{scriptHorizontal}@indexcode{scriptHorizontal}
+ Put scripts left or right of note heads. Support for this is
+ limited. Accidentals will collide with scripts.
+
+ @item @code{slurVerticalDirection}@indexcode{slurVerticalDirection}
+ Set to @code{\free} for free choice of slur direction, set to
+ @code{\up} to force slurs up, set to @code{\down} to force slurs
+ down. The shorthands @code{\slurup}@keyindex{slurup},
+ @code{\slurdown}@keyindex{slurdown}, and
+ @code{\slurboth}@keyindex{slurboth} are available.
+
+ @item @code{slurDash}@indexcode{slurDash}
+ Set to 0 for normal slurs, 1 for dotted slurs, and a
+ larger value for dashed slurs. Identifiers
+ @code{\slurnormal}@keyindex{slurnormal} and
+ @code{\slurdotted}@keyindex{slurdotted} are predefined to set the
+ first two settings.
+
+@item @code{stemLength}@indexcode{stemLength}
+ Set length of stems. Unit is `@code{interline}/2', so
+ @code{stemLength} defaults to 7.
+
+ @item @code{stemLeftBeamCount}@indexcode{stemLeftBeamCount}
+ Specify the number of beams to draw on the left side of the next
+ note. Overrides automatic beaming. The value is only used once,
+ and then it is erased.
+
+ @item @code{stemRightBeamCount}@indexcode{stemRightBeamCount}
+ Specify the number of beams to draw on the right side of the next
+ note. Overrides automatic beaming. The value is only used once,
+ and then it is erased.
+ @item @code{tieVerticalDirection}@indexcode{tieVerticalDirection}
+ Set to @code{\free} for free choice of tie direction, set to
+ @code{\up} to force ties up, set to @code{\down} to force ties
+ down.
+
+ @item @code{transposing}@indexcode{transposing}
+ Transpose the MIDI output. Set this property to the number of
+ half-steps to transpose by.
+
+
+ @item @code{textEmptyDimension}@indexcode{textEmptyDimension}
+ If set to 1 then text placed above or below the staff is
+ assumed to have zero width.
+
+ @item @code{textStyle}@indexcode{textStyle}
+ Set the text style for superscripts and subscripts. See above
+ for list of text styles.
+
+ @item @code{textScriptPadding}@indexcode{textScriptPadding}
+ Determines the extra space added between superscripted resp.
+ subscripted text and the closest staff line or note.
+
+ @item @code{verticalDirection}@indexcode{verticalDirection}
+ Determines the direction of stems, subscripts, beams, slurs, and
+ ties. Set to @code{\down} to force them down, @code{\up} to force
+ them up, or @code{\free} to let LilyPond decide. This can be used
+ to distinguish between voices on the same staff. The
+ @code{\stemdown}@keyindex{stemdown}, @code{\stemup}@keyindex{stemup},
+ and @code{\stemboth}@keyindex{stemboth} identifiers set this
+ property.
+
+
+ @item @code{tupletDirection}@indexcode{tupletDirection}
+ Determines the direction of triplets and other tuplets. Set to
+ @code{\down} to force them below the staff, @code{\up} to force
+ them above, or @code{\free} to let LilyPond decide.
+
+ @item @code{tupletVisibility}@indexcode{tupletVisibility}
+ Determines whether tuplets of notes are labelled. Setting
+ to 0 shows nothing; setting to 1 shows a number;
+ setting to 2 shows a number and a bracket if there is no
+ beam; setting to 3 shows a number, and if there is no beam
+ it adds a bracket; setting to 4 shows both a number and a
+ bracket unconditionally.
+
+@end table
+
+@subsubheading Staff properties
+
+@cindex properties!Staff
+
+@table @samp
+
+ @item @code{barNonAuto}@indexcode{barNonAuto}
+ If set to 1 then bar lines will not be printed
+ automatically; they must be explicitly created with @code{\bar}
+ keywords. Unlike with the @code{\cadenza} keyword, measures are
+ still counted. Bar generation will resume according to that
+ count if this property is set to zero.
+
+ @item @code{barNumberDirection}@indexcode{barNumberDirection}
+ Set to @code{\up} or @code{\down} to put bar numbers above or below
+ the staff.
+
+ @item @code{barNumberHangOnClef}@indexcode{barNumberHangOnClef}
+ Set to 1 to cause bar numbers to appear above or below the
+ clef instead of on the bar line. This property is deprecated.
+ Do not use.
+
+ @item @code{barNumberScriptPadding}@indexcode{barNumberScriptPadding}
+ Sets extra space between the bar number and the bar it labels.
+
+ @item @code{barSize}@indexcode{barSize}
+ Specify the height of the bar lines if it should be different
+ than the staff height.
+
+ @item @code{barAtLineStart}@indexcode{barAtLineStart}
+ Set to 1 to produce a bar line after the clef at the start
+ of each line (but not at the beginning of the music).
+
+ @item @code{clefStyle}@indexcode{clefStyle}
+ Determines how clefs are typeset. If set to @code{transparent},
+ the clefs are not printed at all, if set to
+ @code{fullSizeChanges}, clef changes in the middle of a line are
+ typeset with a full size clef. By default, clef changes are
+ typeset in smaller size.
+
+ @item @code{createKeyOnClefChange}@indexcode{createKeyOnClefChange}
+ Set to a nonempty string if you want key signatures to be printed
+ when the clef changes. Set to the empty string if you do not
+ want key signatures printed.
+
+ @item @code{createInitdefaultClef}@indexcode{createInitdefaultClef}
+ Specify whether clefs are created on default? (Doesn't seem to
+ do anything.)
+
+ @item @code{defaultClef}@indexcode{defaultClef}
+ Determines the default clef. See @code{\clef} keyword.
+
+ @item @code{markHangOnClef}@indexcode{markHangOnClef}
+ Set to 1 to cause marks to appear by clefs instead of by bar
+ lines. Deprecated, use is not recommended.
+
+ @item @code{marginDirection}@indexcode{marginDirection}
+ Set to @code{\left} or @code{\right} to specify location of
+ marginal scripts.
+
+ @item @code{marginScriptPadding}@indexcode{marginScriptPadding}
+ Specify extra space for marginal scripts.
+
+ @item @code{forgetAccidentals}@indexcode{forgetAccidentals}
+ Causes accidentals to be printed at every note instead of
+ remembered for the duration of a measure.
+
+ @item @code{noResetKey}@indexcode{noResetKey}
+ Do not reset the key at the start of a measure. Accidentals will
+ be printed only once and are in effect until overridden, possibly
+ many measures later.
+
+ @item @code{staffLineLeading}@indexcode{staffLineLeading}
+ Specifies the distance (in points) between lines of the staff.
+
+ @item @code{numberOfStaffLines}@indexcode{numberOfStaffLines}
+ Specifies the number of staff lines. The default is 5.
+
+ @item @code{postBreakPadding}@indexcode{postBreakPadding}
+ Extra space in points to be added after the clef, time signature
+ and key signature on the staff. Deprecated, do not use.
+
+ @item @code{noVoltaBraces}@indexcode{noVoltaBraces}
+ Set to true to suppress the printing of brackets over alternate
+ endings specified by the command @code{\alternative}.
+
+ @item @code{numberOfStaffLines}@indexcode{numberOfStaffLines}
+ Sets the number of lines that the staff has.
+
+ @item @code{barAlways}@indexcode{barAlways}
+ If set to 1 a bar line is drawn after each note.
+
+ @item @code{defaultBarType}@indexcode{defaultBarType}
+ Sets the default type of bar line. See Section XREF-barlines [FIXME]
+ for a list of available bar types.
+
+ @item @code{instrument}, @code{instr}
+ @indexcode{instrument}@indexcode{instr}
+ If @code{Staff_margin_engraver}
+@cindex Staff_margin_engraver
+ is
+ added to the Staff translator, then the @code{instrument} property
+ is used to label the first line of the staff and the @code{instr}
+ property is used to label subsequent lines. If the
+ @code{midiInstrument} property is not set, then @code{instrument}
+ is used to determine the instrument for MIDI output.
+
+ @item @code{keyOctaviation}@indexcode{keyOctaviation}
+ If set to 1, then keys are the same in all octaves. If set
+ to 0 then the key signature for different octaves can be
+ different and is specified independently:
+
+ @example
+ \keysignature bes fis'
+ @end example
+
+ The default value is 1. Can be set to zero with
+ @code{\specialkey} or reset to 1 with @code{\normalkey}.
+
+ @item @code{timeSignatureStyle}@indexcode{timeSignatureStyle}
+ Changes the default two-digit layout for time signatures. The
+ following values are recognized:
+
+ @table @samp
+ @item @code{C}@indexcode{C}
+ 4/4 and 2/2 are typeset as C and struck C, respectively. All
+ other time signatures are written with two digits.
+
+ @item @code{old}@indexcode{old}
+ 2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8 and 9/8 are
+ typeset with old-style mensuration marks. All other time
+ signatures are written with two digits.
+
+ @item @code{1}@indexcode{1}
+ All time signatures are typeset with a single
+ digit, e.g. 3/2 is written as 3.
+
+ @item @indexcode{CM/N}@code{C}@var{M}@code{/}@var{N},
+ @indexcode{oldM/N}@code{old}@var{M}@code{/}@var{N} or
+ @code{old6/8alt}@indexcode{old6/8alt}
+ Tells LilyPond to use a specific symbol as time signature.
+ @end table
+
+ The different time signature characters are shown below with its
+ names:
+
+ @mudela[center]
+
+ \score {
+ \notes\relative c'' {
+ \property Voice.textStyle = typewriter
+ \property Staff.timeSignatureStyle = "C2/2"
+ \time 2/2; a2^"C2/2" a2
+ \property Staff.timeSignatureStyle = "C4/4"
+ \time 2/2; a2^"C4/4" a2
+ \property Staff.timeSignatureStyle = "old2/2"
+ \time 2/2; a2^"old2/2" a2
+ \property Staff.timeSignatureStyle = "old3/2"
+ \time 2/2; a2^"old3/2" a2
+ \property Staff.timeSignatureStyle = "old2/4"
+ \time 2/2; a2^"old2/4" a2
+ \property Staff.timeSignatureStyle = "old4/4"
+ \time 2/2; a2^"old4/4" a2
+ \property Staff.timeSignatureStyle = "old6/4"
+ \time 2/2; a2^"old6/4" a2
+ \property Staff.timeSignatureStyle = "old9/4"
+ \time 2/2; a2^"old9/4" a2
+ \property Staff.timeSignatureStyle = "old4/8"
+ \time 2/2; a2^"old4/8" a2
+ \property Staff.timeSignatureStyle = "old6/8"
+ \time 2/2; a2^"old6/8" a2
+ \property Staff.timeSignatureStyle = "old6/8alt"
+ \time 2/2; a2^"old6/8alt" a2
+ \property Staff.timeSignatureStyle = "old9/8"
+ \time 2/2; a2^"old9/8" a2
+ }
+ \paper {
+ linewidth = 4.5 \in;
+ }
+ }
+
+@end mudela
+
+ @item @code{voltaSpannerDuration}@indexcode{voltaSpannerDuration}
+ Set to an integer to control the size of the brackets printed by
+ @code{\alternative}. The integer specifies the number of whole
+ notes duration to use for the brackets. It is rounded to the
+ nearest measure. This can be used to shrink the length of
+ brackets in the situation where one alternative is very large.
+ It may have odd effects if the specified duration is longer than
+ the music given in an @code{\alternative}.
+@end table
+
+
+@cindex properties!GrandStaff
+
+@table @samp
+ @item @code{alignmentReference}@indexcode{alignmentReference}
+ Set to @code{\center} for vertical alignment reference point to be
+ in the center of the vertical group. Set to @code{\up} to put the
+ reference point at the top of the group.
+
+ @item @code{maxVerticalAlign}@indexcode{maxVerticalAlign}
+ Set the maximum vertical distance between staffs.
+
+ @item @code{minVerticalAlign}@indexcode{minVerticalAlign}
+ Set the minimum vertical distance between staffs.
+@end table
+
+
+@cindex properties!Score
+
+@table @samp
+ @item @code{skipBars}@indexcode{skipBars}
+ Set to 1 to skip the empty bars that are produced by
+ multimeasure notes and rests. These bars will not appear on the
+ printed output. Set to zero (the default) to expand multimeasure
+ notes and rests into their full length, printing the appropriate
+ number of empty bars so that synchronization with other voices is
+ preserved.
+
+ @quotation
+
+@mudela[fragment,verbatim,center]
+r1 r1*3 R1*3\property Score.skipBars=1 r1*3 R1*3
+
+@end mudela
+ @end quotation
+
+@end table
+
+
+@cindex properties!ChordNamesVoice
+
+@table @samp
+ @item @code{chordInversion}@indexcode{chordInversion}
+ Determines whether LilyPond should look for chord inversions when
+ translating from notes to chord names. Set to 1 to find
+ inversions. The default is 0 which does not look for
+ inversions.
+@end table
+
+
+
+@node Notation output definitions, , , Reference Manual
+@section Notation output definitions
+
+@cindex output
+
+@cindex notation output
+
+@cindex output definition
+
+@node paper, , , Reference Manual
+
+The most important output definition is the @code{\paper} block, for
+music notation. The syntax is
+
+@example
+
+ @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
+@end example
+
+where each of the items is one of
+
+@itemize @bullet
+ @item An assignment. The assignment must be terminated by a
+ semicolon. See section XREF-papervars [FIXME] for information on
+ paper variables.
+
+ @item A context definition. See section XREF-contextdefs [FIXME] for
+ more information on context definitions.
+
+ @item A margin shape declaration. The syntax is
+
+ @example
+
+ \shape @var{indent1}@code{,} @var{width1}@code{,}
+ @var{indent2}@code{,} @var{width2} @dots{} @code{;}
+ @end example
+
+ @keyindex{shape}
+
+ Each pair of @var{indent} and @var{width} values is a dimension
+ specifying how far to indent and how wide to make the line.
+ The indentation and width of successive lines are specified by
+ the successive pairs of dimensions. The last pair of
+ dimensions will define the characeristics of all lines beyond
+ those explicitly specified.
+
+ @item A font declaration. Its syntax is
+
+ @example
+
+ @var{fontsize} @code{=} \font@keyindex{font} @var{fontname}
+ @end example
+
+ @var{fontsize} is an integer describing the font to be used.
+ 0 is the default font. @var{fontname} is the basename of
+ a font (usually a member of the Feta family).
+@end itemize
+
+
+
+@cindex changing font size and paper size
+
+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.
+
+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{paper_eleven},
+@code{paper_thirteen}, @code{paper_sixteen}, @code{paper_twenty},
+@code{paper_twentythree}, and @code{paper_twentysix} are defined
+respectively. The default @code{\paper} block is also set.
+
+To change the paper size, you must first set the
+@code{papersize}@indexcode{papersize} variable at top level. 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. The new paper size will not
+take effect if the font is not loaded and selected afterwards. Paper
+size selection works by loading a file named after the paper size you
+select.
+
+
+
+@cindex paper variables
+
+@node papervars, , , Reference Manual
+
+There is a large number of paper variables that are used to control
+details of the layout. These variables control the defaults for the
+entire score. Usually, they do not have to be changed; they are by
+default set to values that depend on the font size in use. The
+values are used by the graphic objects while formatting the score;
+they are therefore implementation dependent. Most variables are
+accompanied by documentation in the initalization file
+@file{params.ly} or @file{paperSZ.ly}, where @code{SZ} is the staff
+height in points.
+
+Nevertheless, here are some variables you may want to use or change:
+
+@table @samp
+ @item @code{indent}@indexcode{indent}
+ The indentation of the first line of music.
+
+ @item @code{interline}@indexcode{interline}
+ The distance between two staff lines, calculated from the center
+ of the lines. You should use either this or @code{rulethickness}
+ as a unit for distances you modify.
+
+ @item @code{linewidth}@indexcode{linewidth}
+ Sets the width of the lines. If set to -1.0, a single
+ unjustified line is produced.
+
+ @item @code{output}@indexcode{output}
+ Specifies an alternate name for the the output @file{s}.
+ A @file{.tex}, @file{.midi} or @file{.ps} extension will be
+ added to the string you specify.
+
+ @item @code{rulethickness}@indexcode{rulethickness}
+ Determines the thickness of staff and bar lines.
+
+ @item @code{castingalgorithm}@indexcode{castingalgorithm}
+ The algorithm to use for breaking lines. Choices are
+ @code{\Gourlay}@keyindex{Gourlay} for a TeX-like dynamic
+ programming algorithm, and @code{\Wordwrap}@keyindex{Wordwrap} for
+ a simple algorithm. Gourlay breaking looks much better, but
+ takes a lot more resources. Wordwrap leaves loosely spaced lines
+ at the end.
+@end table
+
+
+@node contextdefs, , , Reference Manual
+
+@cindex context definition
+
+A notation contexts is defined by the following information
+
+@enumerate i
+ @item A name.
+
+ @item The LilyPond modules that do the actual conversion of music to
+ notation. Each module is a so-called
+ @emph{engraver}
+@cindex engraver
+.
+
+ @item How these modules should cooperate, i.e. which ``cooperation
+ module'' should be used. This cooperation module is a special
+ type of engraver.
+
+ @item What other contexts the context can contain,
+
+ @item What properties are defined.
+@end enumerate
+
+A context definition has this syntax:
+
+@example
+
+ \translator @code{@{}
+ @var{translatorinit} @var{translatormodifierlist}
+ @code{@}}
+@end example
+
+@var{translatorinit} can be an identifier or of the form
+
+@example
+
+ \type @var{typename} @code{;}
+@end example
+
+@var{typename} is one of
+
+@table @samp
+ @item @code{Engraver_group_engraver}@indexcode{Engraver_group_engraver}
+ The standard cooperation engraver.
+
+ @item @code{Score_engraver}@indexcode{Score_engraver}
+ This is cooperation module that should be in the top level context.
+
+ @item @code{Grace_engraver_group}@indexcode{Grace_engraver_group}
+ This is a special cooperation module (resembling
+ @code{Score_engraver}) that is used to created an embedded
+ `miniscore'.
+@end table
+
+@var{translatormodifierlist} is a list of items where each item is
+one of
+
+@itemize @bullet
+ @item @code{\consists} @var{engravername} @code{;}
+ Add @var{engravername} to the list of modules in this context.
+ Section XREF-engravers [FIXME] contains an overview of the engravers
+ available. The order of engravers added with @code{\consists} is
+ significant.
+
+ @item @code{\consistsend} @var{engravername} @code{;}
+ Analogous to @code{\consists}, but makes sure that
+ @var{engravername} is always added to the end of the list of
+ engravers.
+
+ Some engraver types need to be at the end of the list; this
+ insures they are put there, and stay there, if a user adds or
+ removes engravers. This command is usually not needed for
+ end-users.
+
+ @item @code{\accepts} @var{contextname} @code{;}
+ Add @var{contextname} to the list of context this context can
+ contain. The first listed context the context to create by
+ default.
+
+ @item @code{\remove} @var{engravername} @code{;}
+ Remove a previously added (with @code{\consists}) engraver.
+
+ @item @code{\name} @var{contextname} @code{;}
+ This sets name of the context, e.g. @code{Staff}, @code{Voice}. If
+ the name is not specified, the translator won't do anything.
+
+ @item @var{propname} @code{=} @var{value} @code{;}
+ A property assignment. It is allowed to use reals for
+ @var{value}.
+@end itemize
+
+In the @code{\paper} block, it is also possible to define translator
+identifiers. Like other block identifiers, the identifier can only
+be used as the very first item of a translator. In order to define
+such an identifier outside of @code{\score}, you must do
+
+@quotation
+
+@example
+\paper @{
+ foo = \translator @{ @dots{} @}
+@}
+\score @{
+ \notes @{
+ @dots{}
+ @}
+ \paper @{
+ \translator @{ \foo @dots{} @}
+ @}
+@}
+@end example
+
+@end quotation
+
+
+@cindex paper types, engravers, and pre-defined translators
+
+Some pre-defined identifiers can simplify modification of
+translators. The pre-defined identifiers are:
+
+@table @samp
+ @item @code{StaffContext}@indexcode{StaffContext}
+ Default Staff context.
+
+ @item @code{RhythmicStaffContext}@indexcode{RhythmicStaffContext}
+ Default RhythmicStaff context.
+
+ @item @code{VoiceContext}@indexcode{VoiceContext}
+ Default Voice context.
+
+ @item @code{ScoreContext}@indexcode{ScoreContext}
+ Default Score context.
+
+ @item @code{ScoreWithNumbers}@indexcode{ScoreWithNumbers}
+ Score context with numbering at the Score level.
+
+ @item @code{BarNumberingStaffContext}@indexcode{BarNumberingStaffContext}
+ Staff context with numbering at the Staff level.
+
+ @item @code{HaraKiriStaffContext}@indexcode{HaraKiriStaffContext}
+ Staff context that does not print if it only contains rests.
+ Useful for orchestral scores.@footnote{Harakiri, also called
+ Seppuku, is the ritual suicide of the Samourai.}
+
+ @item @code{OrchestralPartStaffContext}@indexcode{OrchestralPartStaffContext}
+
+ @item @code{OrchestralScoreContext}@indexcode{OrchestralScoreContext}
+@end table
+
+Using these pre-defined values, you can remove or add items to the
+translator:
+
+@quotation
+
+@example
+\paper @{
+ \translator @{
+ \StaffContext
+ \remove Some_engraver;
+ \consists Different_engraver;
+ @}
+@}
+@end example
+
+@end quotation
+
+
+
+@node engravers, , , Reference Manual
+
+The engravers for paper output are:
+
+[incomplete, FIXME]
+
+@table @samp
+ @item @code{Bar_engraver}@indexcode{Bar_engraver}
+ Engraves bar lines. Normally in @code{Staff} and
+ @code{RhythmicStaff}.
+
+ @item @code{Bar_number_engraver}@indexcode{Bar_number_engraver}
+ Engrave bar numbers. These numbers appear at the start of each
+ line. Not normally in any translator. Can be added to
+ @code{Score} for score-wide numbering or to @code{Staff} for
+ numbering on each staff.
+
+ @item @code{Beam_engraver}@indexcode{Beam_engraver}
+ Handles beam requests by engraving beams. Normally appears in
+ the @code{Voice} translator. If omitted, then notes will be
+ printed with flags instead of beams.
+
+ @item @code{Beam_req_swallow_translator}
+ @indexcode{Beam_req_swallow_translator}
+ Swallows beam requests. In @code{LyricVoice}.
+
+ @item @code{Chord_name_engraver}@indexcode{Chord_name_engraver}
+ Engraves chord names. Normally in @code{ChordNameVoice} .
+
+ @item @code{Chord_tremolo_engraver}@indexcode{Chord_tremolo_engraver}
+
+ @item @code{Clef_engraver}@indexcode{Clef_engraver}
+ Engraves the clef symbol. Normally in @code{Staff}.
+
+ @item @code{Collision_engraver}@indexcode{Collision_engraver}
+
+ @item @code{Dot_column_engraver}@indexcode{Dot_column_engraver}
+ Engraves dots on dotted notes shifted to the right of the note.
+ Normally in @code{Voice}. If omitted, then dots appear on top of
+ the notes.
+
+ @item @code{Dynamic_engraver}@indexcode{Dynamic_engraver}
+ Engraves dynamics symbols. Normally in @code{Voice}.
+
+ @item @code{Font_size_engraver}@indexcode{Font_size_engraver}
+
+ @item @code{Key_engraver}@indexcode{Key_engraver}
+ Engraves the key signature. Normally in @code{Staff}.
+
+ @item @code{Local_key_engraver}@indexcode{Local_key_engraver}
+
+ @item @code{Lyric_engraver}@indexcode{Lyric_engraver}
+ Engraves lyrics. Normally in @code{LyricVoice}.
+
+ @item @code{Multi_measure_rest_engraver}
+ @indexcode{Multi_measure_rest_engraver}
+ Engraves multi-measure rests that are produced with @code{R}.
+ Normally in @code{Voice}.
+
+ @item @code{Piano_bar_engraver}@indexcode{Piano_bar_engraver}
+
+ @item @code{Pitch_squash_engraver}@indexcode{Pitch_squash_engraver}
+ Treat all pitches as middle C. Used in @code{RhythmicStaff}.
+ Note that the notes move, but the locations of accidentals stay
+ the same.
+
+ @item @code{Priority_horizontal_align_engraver}
+ @indexcode{Priority_horizontal_align_engraver}
+
+ @item @code{Repeat_engraver}@indexcode{Repeat_engraver}
+ Handles repeats? In @code{Staff} and @code{RhythmicStaff}.
+
+ @item @code{Rest_collision_engraver}@indexcode{Rest_collision_engraver}
+ Handles collisions of rests. In @code{Staff}.
+
+ @item @code{Rest_engraver}@indexcode{Rest_engraver}
+ Engraves rests. Normally in @code{Voice}.
+
+ @item @code{Rhythmic_column_engraver}@indexcode{Rhythmic_column_engraver}
+
+ @item @code{Score_priority_engraver}@indexcode{Score_priority_engraver}
+
+ @item @code{Script_engraver}@indexcode{Script_engraver}
+ Handles note ornaments generated by @code{\script}. Normally in
+ @code{Voice}.
+
+ @item @code{Separating_line_group_engraver}
+ @indexcode{Separating_line_group_engraver}
+
+ @item @code{Skip_req_swallow_translator}
+ @indexcode{Skip_req_swallow_translator}
+
+ @item @code{Slur_engraver}@indexcode{Slur_engraver}
+ Engraves slurs. Normally in @code{Voice}.
+
+ @item @code{Span_bar_engraver}@indexcode{Span_bar_engraver}
+ Engraves lines across multiple staffs. Normally in
+ @code{Staffgroup} and @code{GrandStaff}. Removing this from
+ @code{StaffGroup} gives the definition of @code{ChoirStaff}.
+
+ @item @code{Span_score_bar_engraver}@indexcode{Span_score_bar_engraver}
+
+ @item @code{Staff_group_bar_engraver}@indexcode{Staff_group_bar_engraver}
+
+ @item @code{Staff_margin_engraver}@indexcode{Staff_margin_engraver}
+ Prints the name of the instrument (specified by
+ @code{Staff.instrument} and @code{Staff.instr}) at the left of the
+ staff.
+
+ @item @code{Staff_sym_engraver}@indexcode{Staff_sym_engraver}
+
+ @item @code{Stem_engraver}@indexcode{Stem_engraver}
+ Engraves stems. Normally in @code{Voice}.
+
+ @item @code{Ties_engraver}@indexcode{Ties_engraver}
+ Engraves ties. Normally in @code{Voice}.
+
+ @item @code{Time_signature_engraver}@indexcode{Time_signature_engraver}
+ Engraves the time signature. Normally in @code{Staff} and
+ @code{RhythmicStaff}.
+
+ @item @code{Timing_engraver}@indexcode{Timing_engraver}
+ Responsible for synchronizing timing information from staffs.
+ Normally in @code{Score}. In order to create polyrhythmic music,
+ this engraver should be removed from @code{Score} and placed in
+ @code{Staff}.
+
+ @item @code{Tuplet_engraver}@indexcode{Tuplet_engraver}
+ Engraves tuplet brackets? In @code{Staff}.
+
+ @item @code{Vertical_align_engraver}@indexcode{Vertical_align_engraver}
+@end table
+
+
+
+@node Sound output, , , Reference Manual
+@section Sound output
+
+
+
+The MIDI block is analogous to the paper block, but it is simpler.
+The @code{\midi} block can contain:
+@cindex MIDI block
+
+@itemize @bullet
+ @item a @code{\tempo} definition
+ @item context definitions
+@end itemize
+
+Assignments in the @code{\midi} block are not allowed.
+
+
+
+@cindex context definition
+
+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}.
+
+
+
+@cindex MIDI instrument names
+
+@node midilist, , , Reference Manual
+
+The MIDI instrument name is set by the
+@code{Staff.midiInstrument}@indexcode{Staff.midiInstrument} property or,
+if that property is not set, the
+@code{Staff.instrument}@indexcode{Staff.instrument} property. The
+instrument name should be chosen from the following list. If the
+selected string does not exactly match, then LilyPond uses the default
+piano.
+
+
+@quotation
+
+@example
+"acoustic grand" "contrabass" "lead 7 (fifths)"
+"bright acoustic" "tremolo strings" "lead 8 (bass+lead)"
+"electric grand" "pizzicato strings" "pad 1 (new age)"
+"honky-tonk" "orchestral strings" "pad 2 (warm)"
+"electric piano 1" "timpani" "pad 3 (polysynth)"
+"electric piano 2" "string ensemble 1" "pad 4 (choir)"
+"harpsichord" "string ensemble 2" "pad 5 (bowed)"
+"clav" "synthstrings 1" "pad 6 (metallic)"
+"celesta" "synthstrings 2" "pad 7 (halo)"
+"glockenspiel" "choir aahs" "pad 8 (sweep)"
+"music box" "voice oohs" "fx 1 (rain)"
+"vibraphone" "synth voice" "fx 2 (soundtrack)"
+"marimba" "orchestra hit" "fx 3 (crystal)"
+"xylophone" "trumpet" "fx 4 (atmosphere)"
+"tubular bells" "trombone" "fx 5 (brightness)"
+"dulcimer" "tuba" "fx 6 (goblins)"
+"drawbar organ" "muted trumpet" "fx 7 (echoes)"
+"percussive organ" "french horn" "fx 8 (sci-fi)"
+"rock organ" "brass section" "sitar"
+"church organ" "synthbrass 1" "banjo"
+"reed organ" "synthbrass 2" "shamisen"
+"accordion" "soprano sax" "koto"
+"harmonica" "alto sax" "kalimba"
+"concertina" "tenor sax" "bagpipe"
+"acoustic guitar (nylon)" "baritone sax" "fiddle"
+"acoustic guitar (steel)" "oboe" "shanai"
+"electric guitar (jazz)" "english horn" "tinkle bell"
+"electric guitar (clean)" "bassoon" "agogo"
+"electric guitar (muted)" "clarinet" "steel drums"
+"overdriven guitar" "piccolo" "woodblock"
+"distorted guitar" "flute" "taiko drum"
+"guitar harmonics" "recorder" "melodic tom"
+"acoustic bass" "pan flute" "synth drum"
+"electric bass (finger)" "blown bottle" "reverse cymbal"
+"electric bass (pick)" "skakuhachi" "guitar fret noise"
+"fretless bass" "whistle" "breath noise"
+"slap bass 1" "ocarina" "seashore"
+"slap bass 2" "lead 1 (square)" "bird tweet"
+"synth bass 1" "lead 2 (sawtooth)" "telephone ring"
+"synth bass 2" "lead 3 (calliope)" "helicopter"
+"violin" "lead 4 (chiff)" "applause"
+"viola" "lead 5 (charang)" "gunshot"
+"cello" "lead 6 (voice)"
+@end example
+
+@end quotation
+
+
+@cindex MIDI types and performers
+
+The types available for MIDI translators are:
+
+@table @samp
+ @item @code{Performer_group_performer}@indexcode{Performer_group_performer}
+ @item @code{Score_performer}@indexcode{Score_performer}
+ @item @code{Staff_performer}@indexcode{Staff_performer}
+@end table
+
+The performers for MIDI translators are:
+
+@table @samp
+ @item @code{Key_performer}@indexcode{Key_performer}
+ @item @code{Time_signature_performer}@indexcode{Time_signature_performer}
+ @item @code{Note_performer}@indexcode{Note_performer}
+ @item @code{Lyric_performer}@indexcode{Lyric_performer}
+ @item @code{Swallow_performer}@indexcode{Swallow_performer}
+@end table
+
+
+
+@node Pre-defined Identifiers, , , Reference Manual
+
+@section Pre-defined Identifiers
+
+@cindex pre-defined identifiers
+
+
+Various identifiers are defined in the initialization files to
+provide shorthands for some settings. Most of them are in
+@file{ly/declarations.ly}.
+
+@table @samp
+ @item @code{\break}@keyindex{break}
+ Force a line break in music by using a large argument for the
+ keyword @code{\penalty}.
+
+ @item @code{\center}@keyindex{center}
+ Used for setting direction properties. Equals 0.
+
+ @item @code{\down}@keyindex{down}
+ Used for setting direction setting properties. Is equal
+ to -1.
+
+ @item @code{\free}@keyindex{free}
+ Used for setting direction setting properties. Is equal
+ to 0.
+
+ @item @code{\left}@keyindex{left}
+ Used for setting text alignment property. Is equal to -1.
+
+ @item @code{\nobreak}@keyindex{nobreak}
+ Prevent a line break in music by using a large negative argument
+ for the keyword @code{\penalty}.
+
+ @item @code{\none}@keyindex{none}
+ Used for setting @code{Score.beamslopedamping} and
+ @code{Score.beamquantisation} properties. Is equal to 0.
+
+ @item @code{\normal}@keyindex{normal}
+ Used for setting @code{Score.beamslopedamping} and
+ @code{Score.beamquantisation} properties. Is equal to 1.
+
+ @item @code{\normalkey}@keyindex{normalkey}
+ Select normal key signatures where each octave has the same key
+ signature. This sets the @code{Staff.keyoctaviation} property.
+
+ @item @code{\right}@keyindex{right}
+ Used for setting text alignment property. Is set to 1.
+
+ @item @code{\shiftoff}@keyindex{shiftoff}
+ Disable horizontal shifting of note heads that collide. Sets the
+ @code{Voice.horizontalNoteShift} property.
+
+ @item @code{\shifton}@keyindex{shifton}
+ Enable note heads that collide with other note heads to be
+ shifted horiztonally. Sets the @code{Voice.horizontalNoteShift}
+ property.
+
+ @item @code{\slurboth}@keyindex{slurboth}
+ Allow slurs to be above or below notes. This sets the
+ @code{Voice.slurVerticalDirection} property.
+
+ @item @code{\slurdown}@keyindex{slurdown}
+ Force slurs to be below notes. This sets the
+ @code{Voice.slurVerticalDirection} property.
+
+ @item @code{\slurup}@keyindex{slurup}
+ Force slurs to be above notes. This sets the
+ @code{Voice.slurVerticalDirection} property.
+
+ @item @code{\specialkey}@keyindex{specialkey}
+ Allow key signatures do differ in different octaves. This sets
+ the @code{Staff.keyoctaviation} property.
+
+ @item @code{\stemboth}@keyindex{stemboth}
+ Allow stems, beams, and slurs to point either upwards or
+ downwards, decided automatically by LilyPond. This sets the
+ @code{Voice.verticalDirection} property.
+
+ @item @code{\stemdown}@keyindex{stemdown}
+ Force stems, beams, and slurs to point down. This sets the
+ @code{Voice.verticalDirection} property.
+
+ @item @code{\stemup}@keyindex{stemup}
+ Force stems, beams and slurs to point up. This sets the
+ @code{Voice.verticalDirection} property.
+
+ @item @code{\traditional}@keyindex{traditional}
+ Used for setting the @code{Score.beamquantisation} property. Is
+ equal to 2.
+
+ @item @code{\up}@keyindex{up}
+ Used for setting various direction properties. Is equal
+ to 1.
+@end table
+
+
+
+@node Running LilyPond, , , Reference Manual
+@section Running LilyPond
+
+@cindex running LilyPond
+
+
+When invoked with a filename that has no extension, LilyPond will try
+adding `@file{.ly}' as an extension first, then `@file{.fly}' and
+finally `@file{.sly}' extension. If the filename ends with
+`@file{.fly}', LilyPond processes the file as music using
+`@file{init.fly}'. In this case, LilyPond does something like:
+
+@quotation
+
+@example
+\score @{
+ \notes\relative c @{
+ \input "yourfile.fly"
+ @}
+ \paper@{@}
+ \midi@{@}
+@}
+@end example
+
+@end quotation
+
+The result of `@file{.sly}' is similar except that a single unjustified
+line is produced.
+
+If you invoke LilyPond with a file `@file{foo.}@var{ext}' that doesn't
+have the `@file{.ly}' extension, then LilyPond will look for a file
+called `@file{init.}@var{ext}' and process this file. The file
+`@file{init.}@var{ext}' must contain the @code{\maininput} keyword or
+LilyPond will not read the user specified file.
+
+When LilyPond processes @file{filename.ly} it will produce
+@file{filename.tex} as output. If @file{filename.ly} contains a second
+@code{\paper} keyword, then LilyPond will produce @file{filename-1.tex}
+as well. Subsequent @code{\paper} keywords will produce sequentially
+numbered file names. Several files can be specified; they will each
+be processed independently.@footnote{Not entirely true: The status of
+GUILE is kept.}
+
+@node Glossary, , , Top
+@chapter Glossary
+
+@include glossary.texi
+
+
+@bye
projects / lilypond.git / commitdiff