@menu
* First steps:: Music language of LilyPond
-* Simple legend:: Small table of music language symbols
* Running LilyPond:: Printing music
-* The first real tune:: The first real tune
-* Lyrics and chords:: Lyrics and chords
+* More basics::
+* Printing lyrics::
+* A melody with chords ::
+* More stanzas::
* More movements :: Joining separate pieces of music
* A piano excerpt:: Piano music
+* Fine tuning a piece::
* An orchestral score:: Conductor's score and individual parts
-* Other ways to run LilyPond:: Other ways to run LilyPond
* Integrating text and music:: Integrating text and music
* End of tutorial:: The end
@end menu
-
-The music is described in a text file, using a simple music language.
-LilyPond reads that text file and generates music that you can print or
-view.
-
-Therefore, creating music notation with LilyPond is done in two steps.
-Using a text editor, you write down the notes to print. Then, you run
-LilyPond to get your printed output.
+Operating lilypond is done through text files: to print a piece of
+music, you enter the music in a file. When you run lilypond, that
+file is read, and after some computations, the program produces a file
+containing the sheet music that you can print or view.
This tutorial starts with a small introduction to the LilyPond music
language. After this first contact, we will show you how to run
LilyPond to produce printed output; you should then be able to create
-your first sheets of music.
-
-The tutorial continues with a slightly more elaborate example of real music.
-This piece introduces and explains some finer details of LilyPond.
-Then, a number of more complex examples follow, that will help you to
-produce most complex music with LilyPond.
-
-
-@c title?
+your first sheets of music. The tutorial continues with more and more
+complex examples.
@node First steps
@section First steps
-@c @node Music language of LilyPond
-@c @section Music language of LilyPond
-
-This section shows how easy writing music with LilyPond actually is. If
-you have not seen LilyPond input source before, this section is for you.
-
-The next section has a table (see @ref{Simple legend}) of all symbols
-that are introduced here, you may want to keep an eye on that.
-
-Writing music with LilyPond is explained below by a number of small
-examples. Each example has a small piece of text; the LilyPond input
-that you should type, with the resulting music printed below it.
-
-You get a simple note by typing its note name, from @code{a} through
-@code{g}:
-
+We tsart off with showing how very simple music is entered in
+LilyPond: you get a simple note by typing its note name, from
+@code{a} through @code{g}. So if you enter
@quotation
@example
c d e f g a b
@end example
-
+@end quotation
+then the result looks like this:
+@quotation
@lilypond[fragment]
\property Score.timing = ##f
\property Staff.TimeSignature = \turnOff
@end quotation
@separate
+We will continue with this format: first we show a snippet of input,
+then the resulting output.
+
The length of a note is specified by adding a number, ``@code{1}'' for a
whole note, ``@code{2}'' for a half note, and so on:
@lilypond[fragment]
\property Score.timing = ##f
\property Staff.TimeSignature = \turnOff
-\property Staff.noAutoBeaming = ##t
+\property Staff.autoBeaming = ##f
%\property Staff.Clef = \turnOff
\transpose c'' { a1 a2 a4 a16 a32 }
s16_" "
@end quotation
@separate
-If you don't specify a duration, the previous duration is used:
-
+If you don't specify a duration, the previous one is used:
@quotation
@example
-a a a2 a
+a4 a a2 a
@end example
@c missing clef seems to raise more questions than actual pitch of notes,
@c as these are snippets anyway
@lilypond[fragment]
\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
+\property Staff.TimeSignature \set #'transparent = ##t
%\property Staff.Clef = \turnOff
\transpose c'' { a2. a4 a8. a16 }
s16_" "
@end quotation
@separate
-The meter (or time signature) can be set with the ``@code{\time}'' command:
+The meter (or time signature) can be set with the @code{\time} command:
@quotation
@example
@c a clef here may lead to confusion
@lilypond[fragment]
-\property Staff.Clef = \turnOff
+\property Staff.Clef \set #'transparent = ##t
\time 3/4
s4_" "
\time 6/8
At this point, the piece of music is ready to be printed. This is done
by combining the music with a printing command.
-The printing command is the so-called ``@code{\paper}'' block. You will
-see later that the \paper block is necessary to customize all kinds of
-printing specifics. The music and the \paper block are combined by
+The printing command is the so-called ``@code{\paper}'' block. You
+will see later that the @code{\paper} block is necessary to customize
+printing specifics. The music and the @code{\paper} block are combined by
enclosing them in ``@code{\score @{ ... @}}''. This is what a full
LilyPond source file looks like:
@separate
-We continue with the introduction of the remaining musical constructs.
+@node Running LilyPond
+@section Running LilyPond
+
+In the last section, we explained what kind of things you could enter
+in a lilypond file. In this section we explain how to run LilyPond,
+and how view or print the output. If you have not used LilyPond
+before, want to test your setup of LilyPond, or try to run an example
+file yourself, then read this section. The instructions that follow
+are for running LilyPond on Unix-like systems. Some additional
+instructions for running LilyPond on Windows are given at the end of
+this section.
+
+You begin with opening a terminal window, and start up a text editor.
+For example, open an xterm and execute @code{joe}. In your text editor,
+enter the following input, and save the file as @file{test.ly}:
+
+@quotation
+@example
+\score @{
+ \notes @{ c'4 e' g' @}
+@}
+@end example
+@end quotation
+
+@cindex ly2dvi
+
+@c now this is weird, running ly2dvi to run LilyPond
+@c (therefore name change proposal)
+
+LilyPond is the program that computes the sheet music. All other
+things, such as adding titles, page breaking and other page layout,
+are done by a small wrapper program called
+@code{ly2dvi}. @code{ly2dvi} calls lilypond to render the music, and
+then adds the titling and page layout instructions. To process
+@file{test.ly} with ly2dvi, proceed as follows:
+
+@quotation
+@example
+ly2dvi -P test.ly
+@end example
+@end quotation
+
+You will see the following on your screen:
+
+@quotation
+@example
+GNU LilyPond 1.4.0
+Now processing: `/home/fred/ly/test.ly'
+Parsing...
+Interpreting music...[1]
+ @emph{ ... more interesting stuff ... }
+PS output to `test.ps'...
+DVI output to `test.dvi'...
+@end example
+@end quotation
+@cindex DVI file
+@cindex Viewing music
+@cindex xdvi
+
+The results of the ly2dvi run are two files, @file{test.dvi} and
+@file{test.ps}. The PS file (@file{test.ps}) is the one you can print.
+You can view the PS file using the program ghostview. If a version of
+ghostview is installed on your system, one of these commands will
+produce a window with some music notation on your screen:
+@c eeek
+@quotation
+@example
+ gv test.ps
+ ghostview test.ps
+ ggv test.ps
+ kghostview test.ps
+@end example
+@end quotation
+If you are satisfied with the looks of the music displayed on your
+screen, you can print the PS file by clicking File/Print inside
+ghostview.
+
+The DVI file (@file{test.dvi}) contains the same sheet music in a
+different format. DVI files are more easily processed by the computer,
+so viewing them usually is quicker. Execute @code{xdvi test.dvi} or
+@code{kdvi test.dvi} to view the DVI file. In Xdvi, the mouse buttons
+activate magnifying glasses. Unfortunately, variable symbols, such as
+beams and slurs won't show up in these.
+
+If your DVI viewer does not have a "Print" button, you can print the
+file by executing @code{lpr test.ps}.
+
+@c volgende alinea schrappen?
+
+If your system does not support printing PostScript files, then you
+can install GhostScript, a PostScript emulator. Refer to
+GhostScript's website at @uref{http://www.ghostscript.com}.
+
+@cindex GhostScript
+@cindex @code{lpr}
+@cindex Printing output
+@cindex PostScript
+@cindex PDF
+
+A final option, is to use the popular PDF format. You can get a PDF
+file by running @code{ly2dvi --pdf test.ly}. With the @code{--pdf},
+you will get a DVI, PS and PDF file. The viewers for the PS files also
+accept PDF files, but there are also many other applications for
+viewing PDF files.
+
+If you are familiar with @TeX{}, then one warning is in place: do not
+use other DVI drivers like @code{dvilj}. The @TeX{} coming out of
+LilyPond uses embedded PostScript code, and will not render correctly
+if you use anything different than @code{dvips}.
+
+@cindex dvips
+@cindex dvilj
+@cindex DVI driver
+
+@unnumberedsubsec Windows users
+Windows users start the terminal by clicking on the LilyPond or Cygwin
+icon. Notepad is sufficient for editing the LilyPond file. Viewing
+the PS file can be done with:
+@quotation
+@example
+@code{gsview32 test.ps}
+@end example
+@end quotation
+You can also print from the command line by executing:
+@quotation
+@example
+@code{gsview32 /s test.ps}
+@end example
+@end quotation
+
+
+@strong{SUMMARY}
+
+To run LilyPond, enter a file, and run the command @code{ly2dvi} on
+that file. The resulting files are either DVI or PostScript, and can
+be viewed with @code{xdvi} (unix) and ghostview (unix and windows)
+respectively. The following table summarizes the constructs that were
+discussed in the previous two sections.
+
+@multitable @columnfractions .3 .3 .4
+
+@item @b{Syntax}
+@tab @b{Description}
+@tab @b{Example}
+
+@item @code{1 2 8 16}
+@tab durations
+@tab
+@lilypond[fragment, relative 1]
+\property Staff.TimeSignature = \turnOff
+\property Staff.autoBeaming = ##f
+\property Staff.Clef = \turnOff
+c1 c2 c8 c16
+@end lilypond
+
+@item @code{. ..}
+@tab augmentation dots
+@tab
+@lilypond[fragment, relative 1]
+\property Staff.TimeSignature = \turnOff
+\property Staff.Clef = \turnOff
+c4. c4..
+@end lilypond
+
+@item @code{c d e f g a b }
+@tab scale
+@tab
+@lilypond[fragment, relative 1]
+\property Staff.TimeSignature = \turnOff
+\property Staff.Clef = \turnOff
+c d e f g a b
+@end lilypond
+
+@item @code{\clef treble \clef bass }
+@tab clefs
+@tab
+@lilypond[fragment]
+\property Staff.TimeSignature \set #'transparent = ##t
+\clef treble
+s4_" "
+\clef bass
+s4_" "
+@end lilypond
+
+@item @code{\time 3/4 \time 4/4 }
+@tab time signature
+@tab
+@lilypond[fragment]
+\property Staff.Clef \set #'transparent = ##t
+\time 3/4
+s4_" "
+\time 4/4
+s16_" "
+@end lilypond
+
+@end multitable
-@c maybe legend here?
-Normal rests are entered just like notes with the name ``@code{r}'':
+@node More basics
+@section More basics
+
+We continue with the introduction of the remaining musical constructs.
+Normal rests are entered just like notes, but use the name
+``@code{r}'':
@quotation
@example
@c bit on the long/complex/scary taste
@c cheating a bit: two lines makes for a friendlier look
This example shows notes, ties, octave marks, and rests in action.
-Don't worry about all the quotes.
@quotation
@example
\score @{
\notes @{
\time 4/4
- \clef violin
\key d \minor
+ \clef violin
r4 r8 d''8 cis''4 e''
d''8 a'4. ~ a' b'8
cis''4 cis''8 cis'' bis'4 d''8 cis'' ~
@end quotation
@c accidentals...
-There are some interesting points to note in this example. Firstly,
-accidentals (sharps and flats) don't have to be marked explicitly: you
+There are some interesting points to note in this example.
+Accidentals (sharps and flats) don't have to be marked explicitly: you
just enter the note name, and LilyPond determines whether or not to
-print an accidental. Secondly, bar lines and beams are drawn
-automatically. Thirdly, LilyPond calculates line breaks for you; it
-doesn't matter where you make new lines in the source file.
+print an accidental. Bar lines and beams are drawn automatically.
+LilyPond calculates line breaks for you; it doesn't matter where you
+make new lines in the source file. Finally, the order of time, key and
+clef changes is not relevant: lilypond will use standard notation
+conventions for ordering these items.
The example also indicates that a piece of music written in a high
-register needs lots of quotes. This makes the input a bit unreadable,
+register needs lots of quotes. This makes the input less readable,
and is therefore also a potential source of errors.
-@separate
-
-The solution is to use ``relative octave'' mode. In practice, most
-music is entered using this mode.
-
-To use relative mode, add @code{\relative} before the piece of music.
-You must also give a note from which relative starts, in this case
-@code{c''}.
-
-@c In relative octave mode, quotes are used to mark large jumps in the
-@c melody. Without any quotes or commas, the interval between a note and
-@c its predecessor is assumed to be a fourth or less. Quotes and commas
-@c add octaves in up and down direction.
-
-If you type no octaviation quotes, relative mode chooses the note that
-is closest to the previous one, which is often just the one you need.
+The solution is to use ``relative octave'' mode. In practice, this is
+the most convenient way to copy existing music. To use relative mode,
+add @code{\relative} before the piece of music. You must also give a
+note from which relative starts, in this case @code{c''}. If you type
+no octavation quotes, relative mode chooses the note that is closest
+to the previous one, which is often just the one you need.
@c don't use commas or quotes in this sentence
For example: @code{c f} goes up; @code{c g} goes down:
@c needed better, maybe even redundant explanation
@c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep.
@c in eerste instantie drong het `relative' niet door zonder extra uitleg.
-You can make a large interval by adding octaviation quotes. Note that
+You can make a large interval by adding octavation quotes. Note that
quotes or commas do not determine the absolute height of a note;
the height of a note is relative to the previous one.
@c don't use commas or quotes in this sentence
@end quotation
@separate
+
+@strong{SUMMARY}
+
+The following table summarizes the syntax learned in this section.
+
+@multitable @columnfractions .3 .3 .4
+
+@item @b{Syntax}
+@tab @b{Description}
+@tab @b{Example}
+
+@item @code{r4 r8}
+@tab rest
+@tab
+@lilypond[fragment, relative 1]
+\property Staff.TimeSignature = \turnOff
+\property Staff.Clef = \turnOff
+r4 r8
+@end lilypond
+
+
+@item @code{~}
+@tab tie
+@tab
+@lilypond[fragment, relative 1]
+\property Score.timing = ##f
+\property Staff.TimeSignature = \turnOff
+\property Staff.autoBeaming = ##f
+\property Staff.Clef = \turnOff
+d ~ d
+@end lilypond
+
+
+@item @code{\key es \major }
+@tab key signature
+@tab
+@lilypond[fragment]
+\property Staff.TimeSignature \set #'transparent = ##t
+\clef treble
+\key es \major
+s4
+@end lilypond
+
+@item @code{'}
+@tab raise octave
+@tab
+@lilypond[fragment, relative 1]
+\property Score.timing = ##f
+\property Staff.TimeSignature = \turnOff
+\property Staff.autoBeaming = ##f
+\property Staff.Clef = \turnOff
+a a'
+@end lilypond
+
+@item @code{,}
+@tab lower octave
+@tab
+@lilypond[fragment, relative 1]
+\property Score.timing = ##f
+\property Staff.TimeSignature = \turnOff
+\property Staff.autoBeaming = ##f
+\property Staff.Clef = \turnOff
+c c,
+@end lilypond
+
+@end multitable
+
A slur is drawn across many notes, and indicates bound articulation
(legato). The starting note and ending note are marked with a
``@code{(}'' and a ``@code{)}'' respectively:
@code{\)}.
@c lousy example
+@c ? --hwn
+@c fragment of 1st hrn in Adams' The Chairman Dances, with creative
+@c chromatic thing pasted in front. (admittedly the original doesn't
+@c have a phrasing slur. The problem is that we don't want the slur
+@c and the Phrasing slur to collide. We're trying to make a good
+@c impression here.
+
@quotation
@lilypond[fragment,relative 1, verbatim]
a8(\( ais b ) c cis2 b'2 a4 cis, \) c
@end quotation
In this example, @code{staffA} and @code{staffB} are names that are
-given to the staves. For now, it doesn't matter what names you give, as
-long as each staff has a unique name.
+given to the staves. It doesn't matter what names you give, as long
+as each staff has a unique name.
@separate
We can typeset a melody with two staves now:
@quotation
-@lilypond[verbatim]
+@lilypond[verbatim,singleline]
\score {
\notes
< \context Staff = staffA {
@end ignore
Of course, you can combine beams and ties with chords. Notice that
-beam and tie markings are placed outside the chord markers:
+beam and tie markings must be placed outside the chord markers:
@quotation
@lilypond[relative 0, fragment,verbatim]
r4 [<c8 e g> <c8 f a>] ~ <c8 f a>
@end lilypond
@end quotation
-When you want to combine chords with slurs and dynamics, an annoying
-technical detail crops up: you have type these commands next to the
-notes, which means that they have to be inside the @code{< >}:
+When you want to combine chords with slurs and dynamics, technical
+detail crops up: you have type these commands next to the notes, which
+means that they have to be inside the @code{< >}:
+
@quotation
-@lilypond[relative 0, fragment,verbatim]
+@example
+r4 <c8 e g \> ( > <c e g> <c e g> < ) \! c8 f a>
+@end example
+@lilypond[relative 0, fragment]
+\slurUp
r4 <c8 e g \> ( > <c e g> <c e g> < ) \! c8 f a>
@end lilypond
@end quotation
@separate
-A nasty technical detail also crops up when you start a score with a
-chord:
-
+There is one golden rule that you should keep in mind when writing
+LilyPond input:
+@quotation
+@strong{DO NOT START A PIECE WITH A CHORD}
+@end quotation
+Of course, it is a allowed, but the result might not be what you expect:
@quotation
@lilypond[verbatim,singleline]
-\score { \notes <c'1 e'1> }
+\score { \notes <c'2 e'2> }
@end lilypond
@end quotation
@separate
-The program can not guess that you want the notes on only one staff. To
-force the chord on a staff, add @code{\context Staff} like this:
+If you have a piece that starts with a chord, then you must explicitly
+state that the notes of the chord are to be put on the same staff, in
+the same voice. This is done by specifying @code{\context Staff} for
+the notes:
@quotation
@lilypond[verbatim,singleline]
-\score { \notes \context Staff <c'1 e'1> }
+\score { \notes \context Voice <c'2 e'2> }
@end lilypond
@end quotation
@separate
+@strong{SUMMARY}
-@ignore
-[TODO add some more here
-
-* lyrics, chords (?)
-
-* \header
-
-* identifiers?
-
-]
-@end ignore
-
-This is the end of the simple tutorial. You know the basic ingredients
-of a music file, so this is the right moment to try your at hand at
-doing it yourself: try to type some simple examples, and experiment a
-little.
-
-When you're comfortable with the basics, then you might want to read the
-rest of this chapter. It also a manual in tutorial-style, but it is much
-more in-depth. It will also be very intimidating if you're not familiar
-with the basics. It deals with some of the more advanced features of
-LilyPond. Topics include lyrics, chords, orchestral scores and parts,
-fine tuning output, polyphonic music, and integrating text and music.
-
-
-@c refer to this section
-@node Simple legend
-@section Simple legend
+@multitable @columnfractions .3 .3 .4
+@item @b{Syntax}
+@tab @b{Description}
+@tab @b{Example}
-@c need texinfo-4.0a or later for this
-
-@c both Tim and my father came independently with a request for a
-@c `legend' like this.
-
-@c what should be in it?
-
-
-
-@quotation
-@multitable @columnfractions .10 .20 .40
-
-@item @code{[ ]}
-@tab beam
+@item @code{( )}
+@tab slur
@tab
@lilypond[fragment, relative 1]
\property Score.timing = ##f
\property Staff.TimeSignature = \turnOff
-\property Staff.noAutoBeaming = ##t
+\property Staff.autoBeaming = ##f
\property Staff.Clef = \turnOff
-[a8 b]
+c( d )e
@end lilypond
-@item @code{~}
-@tab tie
+
+@item @code{\( \)}
+@tab phrasing slur
@tab
@lilypond[fragment, relative 1]
\property Score.timing = ##f
\property Staff.TimeSignature = \turnOff
-\property Staff.noAutoBeaming = ##t
+\property Staff.autoBeaming = ##f
\property Staff.Clef = \turnOff
-d ~ d
+c\( c() d \)e
@end lilypond
-@item @code{( )}
-@tab slur
+
+@item @code{[ ]}
+@tab beam
@tab
@lilypond[fragment, relative 1]
\property Score.timing = ##f
\property Staff.TimeSignature = \turnOff
-\property Staff.noAutoBeaming = ##t
+\property Staff.autoBeaming = ##f
\property Staff.Clef = \turnOff
-c( d )e
+[a8 b]
@end lilypond
-@item @code{'}
-@tab raise octave
+
+
+@item @code{< \context Staff ... >}
+@tab more staffs
@tab
-@lilypond[fragment, relative 1]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\property Staff.noAutoBeaming = ##t
-\property Staff.Clef = \turnOff
-a a'
+@lilypond[fragment]
+< \context Staff = SA { c'1 }
+ \context Staff = SB { c'1 } >
@end lilypond
-@item @code{,}
-@tab lower octave
+
+@item @code{-> -.}
+@tab articulations
@tab
@lilypond[fragment, relative 1]
-\property Score.timing = ##f
\property Staff.TimeSignature = \turnOff
-\property Staff.noAutoBeaming = ##t
\property Staff.Clef = \turnOff
-c c,
+c-> c-.
@end lilypond
-@item @code{< >}
-@tab chord
+
+@item @code{-\mf -\sfz}
+@tab dynamics
@tab
@lilypond[fragment, relative 1]
-\property Score.timing = ##f
\property Staff.TimeSignature = \turnOff
-\property Staff.noAutoBeaming = ##t
\property Staff.Clef = \turnOff
-\context Voice { <a c> }
+c-\mf c-\sfz
@end lilypond
+
@item @code{\< \!}
@tab crescendo
@tab
@lilypond[fragment, relative 1]
\property Score.timing = ##f
\property Staff.TimeSignature = \turnOff
-\property Staff.noAutoBeaming = ##t
+\property Staff.autoBeaming = ##f
\property Staff.Clef = \turnOff
a\< a \!a
@end lilypond
@lilypond[fragment, relative 1]
\property Score.timing = ##f
\property Staff.TimeSignature = \turnOff
-\property Staff.noAutoBeaming = ##t
+\property Staff.autoBeaming = ##f
\property Staff.Clef = \turnOff
a\> a \!a
@end lilypond
-@end multitable
-@end quotation
-
-
-
-@node Running LilyPond
-@section Running LilyPond
-
-You write music with LilyPond as follows: first you edit a text file
-containing a description of the notes. Then you run LilyPond on the
-file. This leaves you with an output file, which you can view or print.
-
-In this section we explain how to run LilyPond, and view or print the
-output. If you have not used LilyPond before, want to test your setup
-of LilyPond, or try to run an example file yourself, then read this
-section.
-
-The instructions that follow are for running LilyPond on Unix-like
-systems. Some additional instructions for running LilyPond on Windows
-are given at the end of this section.
-
-You begin with opening a terminal window, and start up a text editor.
-For example, open an xterm and execute @code{joe}. In your text editor,
-enter the following input, and save the file as @file{test.ly}:
-
-@quotation
-@example
-\score @{
- \notes @{ c'4 e' g' @}
-@}
-@end example
-@end quotation
-
-@cindex ly2dvi
-@c now this is weird, running ly2dvi to run LilyPond
-@c (therefore name change proposal)
-
-To run LilyPond, you invoke ly2dvi to compile your LilyPond source file:
-
-@quotation
-@example
-ly2dvi -P test.ly
-@end example
-@end quotation
-
-You will see the following on your screen:
-
-@quotation
-@example
-GNU LilyPond 1.4.0
-Now processing: `/home/fred/ly/test.ly'
-Parsing...
-Interpreting music...[1]
- @emph{ ... more interesting stuff ... }
-PS output to `test.ps'...
-DVI output to `test.dvi'...
-@end example
-@end quotation
-@cindex DVI file
-@cindex Viewing music
-@cindex xdvi
-
-The results of the ly2dvi run are two files, @file{test.dvi} and
-@file{test.ps}. The PS file (@file{test.ps}) is the one you can print.
-You can view the PS file using the program ghostview. If a version of
-ghostview is installed on your system, one of these commands will
-produce a window with some music notation on your screen:
-@c eeek
-@quotation
-@example
- gv test.ps
- ghostview test.ps
- ggv test.ps
- kghostview test.ps
-@end example
-@end quotation
-If you are satisfied with the looks of the music displayed on your
-screen, you can print the PS file by clicking File/Print inside
-ghostview.
-
-The DVI file (@file{test.dvi}) contains the same sheet music in a
-different format. DVI files are more easily processed by the computer,
-so viewing them usually is quicker. Execute @code{xdvi test.dvi}
-to view the DVI file.
-
-If your DVI viewer does not have a "Print" button, you can print the
-file by executing @code{lpr test.ps}.
-
-@c volgende alinea schrappen?
-
-If you can't get the examples to print, then you should look into
-installing and configuring ghostscript. Refer to GhostScript's website
-at @uref{http://www.ghostscript.com}.
-
-@cindex GhostScript
-@cindex @code{lpr}
-@cindex Printing output
-@cindex PostScript
+@item @code{< >}
+@tab chord
+@tab
+@lilypond[fragment, relative 1]
+\context Voice <c e>
+@end lilypond
-@unnumberedsubsec Windows users
-Windows users start the terminal by clicking on the LilyPond or Cygwin
-icon. Notepad is sufficient for editing the LilyPond file. Viewing
-the PS file can be done with:
-@quotation
-@example
-@code{gsview32 test.ps}
-@end example
-@end quotation
-You can also print from the command line by executing:
-@quotation
-@example
-@code{gsview32 /s test.ps}
-@end example
-@end quotation
+@end multitable
+You know the basic ingredients of a music file, so this is the right
+moment to try your at hand at doing it yourself: try to type some
+simple examples, and experiment a little.
-@node The first real tune
-@section The first real tune
+When you're comfortable with the basics, then you might want to read
+the rest of this chapter. It also a manual in tutorial-style, but it
+is much more in-depth, dealing with more advanced topics such as
+lyrics, chords, orchestral scores and parts, fine tuning output,
+polyphonic music, and integrating text and music.
-The rest of this tutorial will demonstrate how to use Lilypond 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/}@footnote{When we refer to filenames,
-they are relative to the top directory of the source package. }
-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 minuet in J. S. Bach's @emph{Klavierb@"uchlein}. The file
-is included in the distribution as @file{minuet.ly}.
-@cindex Bach, Johann Sebastian
-@lilypond[verbatim]
-% all text after a percent sign is a comment
-% and is ignored by LilyPond
-\include "paper16.ly"
-\score {
- \notes
- \relative c'' \sequential {
- \time 3/4
- \key g \major
-
- \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. |
- }
+@node Printing lyrics
+@section Printing lyrics
+@cindex lyrics
- 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 big and wide for a book
- indent = 1.0 \cm
- linewidth = 15.0 \cm
- }
+In this section we shall explain how to typeset the following
+fragment of The Free Software Song:
+
+@lilypond[singleline]
+\score { \notes { \addlyrics
+ \notes \relative c' {
+ \time 7/4
+ d'2 c4 b16 ( a g a b a b ) c a2
+ b2 c4 b8 ( a16 g ) a4 g2 }
+ \context Lyrics \lyrics {
+ Join us now __ and
+ share the soft -- ware; }
+}
+\paper { linewidth = -1. }
}
@end lilypond
-We will analyse the input, line by line.
-@separate
-@example
- % all text after a percent sign is a comment
- % and is ignored by LilyPond
-@end example
-Percent signs introduce comments: everything after a percent sign is
-ignored. You can use this to write down mental notes to yourself. You
-can also make longer comments by enclosing text in @code{%@{} and
-@code{%@}}.
-@cindex comment
-@cindex block comment
-@cindex line comment
-@separate
-@example
- \include "paper16.ly"
-
-@end example
-@cindex @code{\include}
-@cindex point, printer's
-@cindex staff size, setting
-@cindex font size, setting
+@cindex lyric mode
+@cindex @code{\lyrics}
-By default, LilyPond will typeset the music in a size such that each
-staff is 20 point (0.7 cm, or 0.27 inch) high. We want smaller output
-(16 point staff height), so we must import the settings for that size,
-which is done here.
-@separate
-@example
-
- \score @{
-
-@end example
-Music is printed by combining a piece of music with directions for
-outputting it. This combination is formed in the @code{\score} block.
-@separate
-@example
-
- \notes
-
-@end example
-Prepare LilyPond for accepting notes.
-@cindex octaves, choosing
-@cindex pitch
-@separate
-@example
- \relative c''
-
-@end example
-@cindex relative
-@c removed duplicate introduction to octave marks /MB
-@c Shorten even more?
+To print lyrics, you must enter them, and then instruct lilypond to
+handle the lyrics by printing them.
+You can enter lyrics in a special input mode of LilyPond. This mode is
+called Lyrics mode, and it is introduced by the keyword @code{\lyrics}.
+The purpose of this mode is that you can enter lyrics as plain text,
+punctuation and accents without any hassle.
-@c As we will see, each note is described by its note name, duration,
-@c octave and possibly a chromatic alteration. In this setup, the octave
-@c is indicated by using high quotes (@code{'}) and ``lowered quotes''
-@c (commas: @code{,}). The central C is denoted by @code{c'}. The C one
-@c octave higher is @code{c''}. One and two octaves below the central C is
-@c denoted by @code{c} and @code{c,} respectively.
+Syllables are entered like notes, with pitches replaced by text. For
+example, @code{Twin- kle twin- kle} enters four syllables. Note that
+the hyphen has no special meaning for lyrics, and does not introduce
+special symbols.
-Even though a piece of music often spans a range of several octaves, it
-mostly moves in small intervals. LilyPond has a special entry mode to
-save typing in this situation. In this ``relative'' octave mode,
-octaves of notes without quotes are chosen such that a note is as close
-as possible (graphically, on the staff) to the preceding note. If you
-add a high-quote an extra octave is added. A lowered quote (a comma)
-will subtract an extra octave.
+Spaces can be introduced into a lyric either by using quotes:
+@code{"He could"4 not4} or by using an underscore without quotes:
+@code{He_could4 not4}. All unquoted underscores are converted to
+spaces.
-Because the first note has no predecessor,
-you have to give the (absolute) pitch of the note to start with.
-@separate
-@example
+These are the lyrics for the free software song:
- \sequential @{
-
-@end example
-What follows is sequential music, i.e.,
-@cindex sequential music
-notes that are to be played and printed after each other.
-@separate
@example
-
- \time 3/4
-
+ \lyrics @{
+ Join us now __ and
+ share the soft -- ware; @}
@end example
-@cindex time signature, setting
-@cindex @code{\time}
-Set (or change) the time signature of the current piece: a 3/4 sign is
-printed. The time signature setting is also used to generate bar lines
-at the right spots.
-@separate
-@example
- \key g \major
-
-@end example
-@cindex key signature, setting
-@cindex @code{\key}
-Set (or change) the current key signature to G-major. Although in this
-example, the @code{\key} command happened to be entered after the
-@code{\time} command, in the output the time signature will be printed
-after the key signature; LilyPond knows about music typesetting
-conventions.
-@separate
-@example
+As you can see, extender lines are entered as @code{__}. 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{_}).
- \repeat "volta" 2
-
-@end example
-The following piece of music is played twice. The first argument
-indicates the type of repeat. In this case, @code{"volta"} means that
-prima volta/secunda volta brackets are used for the alternative
-endings---if there were any.
-@separate
-@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.
-@separate
-@example
-
- d4 g,8
-
-@end example
-Two notes. The first note is a quarter note with relative pitch
-@code{d}. The relative music was started with a @code{c''}, so the real
-pitch of this note is @code{d''}. The duration of a note is designated
-by a number; the @code{4} here represents a quarter note.
-
-The second note is an eight note with relative pitch @code{g,}. The
-pitch is taken relative to the previous @code{d''}, making this
-note have real pitch @code{g'}. The @code{8} represents an eight note.
-@separate
-@example
-
- a b
-
-@end example
-Two more notes, with pitch @code{a} and @code{b}. Because their
-duration is the same as the @code{g,8}, there is no need to enter the
-duration, but you may enter it anyway, i.e., @code{a8 b8}
-@separate
-@example
-
- d4 g, g |
-
+If you can use have hyphens at the end of a syllable, i.e.
+@example
+ soft- ware
@end example
-@cindex bar check
-@cindex @code{|}
-@cindex errors, finding
-Three more notes. The @code{|} character is a ``bar check''. LilyPond
-will verify that bar checks are found at the start of a measure. This can
-help you track down typing errors.
-
-@cindex alteration, chromatic
-@cindex chromatic alteration
-@separate
-@example
-
- c8 d e fis
-
-@end example
-So far, no notes were chromatically altered. Here is the first one that
-is: @code{fis}. LilyPond by default uses Dutch@footnote{Note names are
-available in several languages, but we find the Dutch names quite
-convenient.} 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.
-
-For groups of eighth notes and shorter, LilyPond can determine how the
-notes should form a beam. In this case, the 4 eights are automatically
-printed as a beam.
-@separate
-@example
-
- c4 d8( )c b a( )b4 c8 b a g |
+but then the hyphen will be attached to the to the end of the first
+syllable.
-@end example
-The beginning and ending notes of a slur are marked with parentheses,
-@code{(} and @code{)} for start and end respectively. The line above
-indicates two slurs. These slur markers (parentheses) are entered
-between the slurred notes.
-@separate
-@example
-
- a4 [b8 a] [g fis]
+If you want them centered between syllables you can use the special
+`@code{-}@code{-}' lyric as a separate word between syllables. The
+hyphen will have variable length depending on the space between
+syllables. It will be centered between the syllables.
-@end example
-Automatic beaming can be overridden by inserting beam marks, @code{[}
-and @code{]}. These beam markers (brackets) are put around the notes
-you want beamed.
-@separate
-@example
+Normally, the notes that you enter are transformed into note heads.
+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
+contexts'. Interpretation contexts exist for generating notation
+(`notation context') and for generating sound (`performance
+context'). These objects only exist during a run of LilyPond.
- g2. |
-
+When LilyPond interprets music, it will create a Staff context.
+We don't want that default here, because we want lyric. The
+command
+@example
+ \context Lyrics
@end example
-@cindex augmentation dot
-@cindex dotted note
-A period adds a dot to the note.
-@separate
-@example
+explicitly creates an interpretation context of
+@code{Lyrics} type to interpret the song text that we entered.
- @}
-
-@end example
-The end of the sequential music to be repeated. LilyPond will typeset a
-repeat bar.
-@separate
-@example
-
- cis'4 b8 cis a4 |
-
-@end example
-Accidentals are printed whenever necessary: the first C sharp of the bar
-will be printed with an accidental, the second one without.
-@separate
-@example
-
- a8-. b-. cis-. d-. e-. fis-.
-
+The melody of the song doesn't offer anything new:
+@example
+ \notes \relative c' @{
+ \time 7/4
+ d'2 c4 b16 ( a g a b a b ) c a2
+ b2 c4 b8 ( a16 g ) a4 g2 @}
@end example
-@cindex articulation
-You can enter articulation signs either in a verbose form or using a
-shorthand. Here we demonstrate the shorthand: it is formed by a dash
-and the character for the articulation to use, e.g. @code{-.} for
-staccato as shown above.
-@separate
-@example
-
- fis a, r8 cis8
-
-@end example
-
-Rests are denoted by the special note name @code{r}.
-@separate
-@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, but it
-is a shorthand for a more complicated description of a fermata symbol.
-@code{\fermata} names that description and is therefore called an
-identifier.
-@cindex identifier
-@cindex @code{\fermata}
-@separate
+Both can be combined with the @code{\addlyrics}:
@example
- \bar "|."
- @}
-@end example
-Here the music ends. LilyPond does not automatically typeset an end
-bar, we must explicitly request one, using @code{"|."}.
-
-@separate
-@example
-
- \paper @{
- % standard settings are too big and wide for a book
- indent = 1.0\cm
- linewidth = 15.0\cm
- @}
-
-@end example
-The @code{\paper} block specifies how entered music should be converted
-to notation output. Most of the details of the conversion (font sizes,
-dimensions, etc.) have been taken care of, but to fit the output in this
-document, it has to be narrower. We do this by setting the line width
-to 14 centimeters (approximately 5.5 inches).
-@separate
-@example
+\addlyrics
+ \notes \relative c' @dots{}
+ \context Lyrics \lyrics @dots{}
+@end example
- @}
-
-@end example
-The last brace ends the @code{\score} block.
+The lyrics are also music expressions, similar to notes. What happens
+here, is that each syllable of the lyrics is put under the a note of
+the melody.
+The complete file is listed here:
+@example
+\score @{ \notes @{ \addlyrics
+ \notes \relative c' @{
+ \time 7/4
+ d'2 c4 b16 ( a g a b a b ) c a2
+ b2 c4 b8 ( a16 g ) a4 g2 @}
+ \context Lyrics \lyrics @{
+ Join us now __ and
+ share the soft -- ware; @}
+@}
+\paper @{ linewidth = -1. @}
+@}
+@end example
-@node Lyrics and chords
-@section Lyrics and chords
+@node A melody with chords
+@section A melody with chords
-In this section we show how to typeset a song. This file is
-included as @file{flowing.ly}.
+In this section we show how to typeset a melody with chord
+accompaniment. This file is included as @file{input/tutorial/flowing.ly}.
@example
-\header @{
- title = "The river is flowing"
- composer = "Traditional"
-@}
\include "paper16.ly"
melody = \notes \relative c' @{
\partial 8
\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
\simultaneous @{
%\accompaniment
\context ChordNames \accompaniment
-
- \addlyrics
\context Staff = mel @{
- \property Staff.noAutoBeaming = ##t
- \property Staff.automaticMelismata = ##t
\melody
@}
- \context Lyrics \text
+
@}
\midi @{ \tempo 4=72 @}
\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
-@code{ly2dvi}.}
-
-@center @strong{The river is flowing}
-@center Traditional
+The result would look this.
@lilypond[center]
-\header {
- title = "The river is flowing"
- composer = "Traditional"
-}
\include "paper16.ly"
melody = \notes \relative c' {
\partial 8
\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
%\accompaniment
\context ChordNames \accompaniment
- \addlyrics
\context Staff = mel {
- \property Staff.noAutoBeaming = ##t
- \property Staff.automaticMelismata = ##t
- \melody
+ \property Staff.autoBeaming = ##f
+ \melody
}
- \context Lyrics \text
}
\midi { \tempo 4=72 }
\paper { linewidth = 10.0\cm }
@end lilypond
Again, we will dissect the file line by line.
-@separate
-@example
-
- \header @{
-
-@end example
-@cindex @code{\header}
-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 passed into the output. @file{ly2dvi} uses this
-information to print titles above the music.
-@separate
-@example
- title = "The river is flowing"
- composer = "Traditional (?)"
-@end example
-@cindex assignments
-@cindex identifier assignment
-the @code{\header} block contains assignments. In each assignment, a
-variable is set to a value. Lexically, both the variable name and the
-assigned value are strings. The values have to be quoted here, because
-they contain spaces. The variable names could also be put within quotes
-but it is not necessary.
@separate
@example
@cindex lyrics
@cindex identifier assignment
@cindex syllables, entering
-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 @{}.
-@separate
-@example
- The4 ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
- ri- ver is flo- __ wing down to the sea.
-@}
-
-@end example
-@cindex extenders, lyric
-@cindex hyphens, lyric
-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.
@separate
@example
@separate
@example
- c2:3- f:3-.7
+ c2:3-
@end example
@cindex tonic
@cindex chord modifier
@cindex modifier, chord
-A chord is started by the tonic of the chord. The
-first one lasts a half note. An unadorned note creates a major
-triad. Since a minor triad is wanted, @code{3-} is added to modify the
-third to be small. @code{7} modifies (adds) a seventh, which is small by
+This is a c minor chord, lasting half a note. Chord are entered by
+entering the tonic. Then notes can be changed. In this case, a small third
+is used. The cod for this is @code{3-}.
+
+@separate
+@example
+f:3-.7
+@end example
+Similarly, @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 dots.
@separate
d:min es4 c8:min r8
@end example
-
Some modifiers have predefined names, e.g. @code{min} is the same as
@code{3-}, so @code{d-min} is a minor @code{d} chord.
@separate
(`notation context') and for generating sound (`performance
context'). These objects only exist during a run of LilyPond.
-By default, LilyPond will create a Staff context for you. If you would
-remove the @code{%} sign in the previous line, you would see that
-mechanism in action.
+When LilyPond interprets music, it will create a Staff context. If
+the @code{%} sign in the previous line were removed, you could see
+that mechanism in action.
We don't want that default here, because we want chord names. The
command above explicitly creates an interpretation context of
@code{ChordNames} type to interpret the music @code{\accompaniment}.
-@separate
-@example
- \addlyrics
-
-@end example
-@cindex @code{\addlyrics}
-@cindex lyrics and melody, combining
-@cindex combining lyrics and melody
-
-The lyrics should 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, and looks
-silly.
@separate
@example
@end example
-The first argument of @code{\addlyrics} is the melody. We instantiate
-a @code{Staff} context explicitly: should you choose to remove the
-comment before the ``note heads'' version of the accompaniment, the
-accompaniment will be on a nameless staff. The melody has to be on
-staff different from the accompaniment. This is accomplished by giving
-the melody and accompaniment staves different names.
+We place the melody on a staff called @code{mel}. We give it a name to
+differentiate it from the one that would contain note heads for the
+chords, if you would remove the comment before the ``note heads''
+version of the accompaniment. By giving this staff a name, it is
+forced to be different.
@separate
@example
- \property Staff.noAutoBeaming = ##t
+ \property Staff.autoBeaming = ##f
@end example
@cindex \property
@cindex context variables
@cindex setting context variables
An interpretation context has variables, called properties, that tune
-its behavior. One of the variables is @code{noAutoBeaming}. Setting
-this @code{Staff}'s property to @code{##t}, which is the boolean value
-@var{true}, turns the automatic beaming mechanism off for the current
+its behavior. One of the variables is @code{autoBeaming}. Setting
+this @code{Staff}'s property to @code{##f}, which is the boolean value
+@var{false}, turns the automatic beaming mechanism off for the current
staff.
-@cindex GUILE
-@cindex Scheme
-@cindex accessing Scheme
-@cindex evaluating Scheme
-@cindex LISP
-
-LilyPond internally uses GUILE, a Scheme-interpreter. Scheme is a
-language from the LISP family. You can learn more about Scheme at
-@uref{http://www.scheme.org}. It is used to represent data throughout
-the whole program. The hash-sign (@code{#}) accesses GUILE directly: the
-code following the hash-sign is evaluated as Scheme. The boolean value
-@var{true} is @code{#t} in Scheme, so for LilyPond @var{true} looks like
-@code{##t}.
-
-If Scheme scares you, don't worry. You don't need to know Scheme to
-create beautiful sheet music.
-
-@separate
-@example
-
- \property Staff.automaticMelismata = ##t
-
-@end example
-@cindex automaticMelismata
-@cindex melismata
-@cindex @code{\addlyrics} and slurs
-Similarly, we don't want to print a syllable when there is
-a slur. This sets up @code{\addlyrics} to not put lyrics under each
-separate note while there is a slur.
@separate
@example
@code{\property} directives and @code{\melody} are grouped in sequential
music, so the property settings are done before the melody is
processed.
-@separate
-@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.
@separate
@example
We also want notation output. The linewidth is short so the piece
will be set in two lines.
-@node More movements
-@section More movements
+@node More stanzas
+@section More stanzas
-[FIXME: merge here with, or move this to: Other ways to run LilyPond]
-You probably ran @file{ly2dvi} on the last example, and ended up with a
-viewable @file{.dvi} file. However, between there are a few steps of
-which LilyPond is only one. To enhance your understanding of what's
-happening under the hood when you run @code{ly2dvi}, we explain what
-programs are run.
+@cindex phrasing
-@code{ly2dvi} is a program that calls a number of programs in sequence.
-The first thing it does, is running LilyPond on the input file. After
-some calculations, a @file{.tex} is produced. The contents
-of this file are very low-level instructions.
+If you have multiple stanzas printed underneath each other, the vertical
+groups of syllables should be aligned around punctuation. LilyPond can
+do this if you tell it which lyric lines belong to which melody.
+We show how you can do this by showing how you could print a frivolous
+fragment of a fictional Sesame Street duet.
-For example, consider the following file (@file{miniatures.ly})
+@lilypond[singleline,verbatim]
+\score {
+\addlyrics
+ \notes \relative c'' \context Voice = duet { \time 3/4
+ g2 e4 a2 f4 g2. }
+ \lyrics \context Lyrics <
+ \context LyricsVoice = "duet-1" {
+ \property LyricsVoice . stanza = "Bert"
+ Hi, my name is bert. }
+ \context LyricsVoice = "duet-2" {
+ \property LyricsVoice . stanza = "Ernie"
+ Ooooo, ch\'e -- ri, je t'aime. }
+ >
+}
+@end lilypond
+To this end, give the Voice context an identity, and set the
+LyricsVoice to a name starting with that identity followed by a dash.
+In the following example, the Voice identity is @code{duet},
@example
-\version "1.4.0"
-\header @{
- title = "Two miniatures"
- tagline = "small is beautiful"
-@}
-
-#(set! point-and-click line-column-location)
-
-\paper @{ linewidth = -1.0 @}
-
-\score @{
- \notes @{ c'4 d'4 @}
- \header @{
- opus = "Opus 1."
- piece = "Up" @}
-@}
-\score @{
- \notes @{ d'4 c'4 @}
- \header @{
- opus = "Opus 2."
- piece = "Down" @}
-@}
+\context Voice = duet @{
+ \time 3/4
+ g2 e4 a2 f4 g2. @}
+@end example
+and the
+identities of the LyricsVoices are @code{duet-1} and @code{duet-2}.
+@example
+ \context LyricsVoice = "duet-1" @{
+ Hi, my name is bert. @}
+ \context LyricsVoice = "duet-2" @{
+ Ooooo, ch\'e -- ri, je t'aime. @}
+@end example
+
+We add the names of the singers. This can be done by setting
+@code{LyricsVoice.Stanza} (for the first system) and
+@code{LyricsVoice.stz} for the following systems. Notice how you must
+surround dots with spaces in @code{\lyrics} mode.
+
+@example
+ \property LyricsVoice . stanza = "Bert"
+ @dots{}
+ \property LyricsVoice . stanza = "Ernie"
@end example
-The titling in this manual was not generated by ly2dvi, so we can't
-exactly show what it would look like, but the result should resemble this:
+
+@node More movements
+@section More movements
+
+LilyPond only handles formatting sheet music. It doesn't concern
+itself with producing titles. This is the jobs of a simple wrapper
+program called ly2dvi. @code{ly2dvi} calls LilyPond to do the
+sheet music formatting. Then it produces titles, and ties together all
+inputs into a single @file{dvi} file. In this section, we show some of
+the options for titling. We will show how you can produce a file
+that looks like this:
@center @strong{Two miniatures}
@flushright
}
@end lilypond
-This file is produced by ly2dvi in a few stages, with the help of text
-formatting tools. LilyPond produces two output files,
-@file{miniatures.tex} and @file{miniatures-1.tex}. Both files contain
-only graphical music notation. @file{ly2dvi} looks at what output
-LilyPond produces, and adds page layout and titling to those files. The
-result is a DVI file called @file{miniatures.dvi}.
+For example, consider the following file (@file{miniatures.ly})
-Next, now we'll look at the example line by line to explain new things.
+@example
+\version "1.5.60"
+\header @{
+ title = "Two miniatures"
+ composer = "F. Bar Baz"
+ tagline = "small is beautiful" @}
-@separate
-@example
-\version "1.4.0"
-@end example
-Lilypond and its language are still under development, and occasionally,
-details of the syntax are changed. This fragment indicates for which
-version the input file was written. When you compile this file, the
-version number will be checked, and you will get a warning when the file
-is too old.
+\paper @{ linewidth = -1.0 @}
-This version number is also used by the @code{convert-ly} program (See
-@ref{convert-ly}), which is used to update the file to the latest lily
-version.
+%@{
-@separate
-@example
- \header @{
- title = "Two miniatures" @}
-@end example
-This sets the titling information for the entire file.
-@separate
-@example
- tagline = "small is beautiful"
+Mental note: discuss Schenkerian analysis of these key pieces.
+
+%@}
+
+
+\score @{
+ \notes @{ c'4 d'4 @}
+ \header @{
+ opus = "Opus 1."
+ piece = "Up" @}
+@}
+\score @{
+ \notes @{ d'4 c'4 @}
+ \header @{
+ opus = "Opus 2."
+ piece = "Down" @}
+@}
@end example
-A signature line is printed at the bottom of the last page.
- This signature is produced from the @code{tagline} field of
-@code{\header}. Many people find the default "Lily was here,
-@var{version number}" too droll. If that is the case, assign
-something else to @code{tagline}, as shown above.
-@separate
-@example
- #(set! point-and-click line-column-location)
+
+The information for the global titling is in a so-called header block.
+The information in this block is not used by
+LilyPond, but it is passed into the output. @file{ly2dvi} uses this
+information to print titles above the music.
+@cindex assignments
+@cindex identifier assignment
+the @code{\header} block contains assignments. In each assignment, a
+variable is set to a value. The header block for this file looks like
+this
+@cindex @code{\header}
+@example
+ \header @{
+ title = "Two miniatures"
+ composer = "F. Bar Baz"
+ tagline = "small is beautiful"
+ @}
@end example
-This piece of Scheme code sets the Scheme variable
-@code{point-and-click} to the value @var{line-column-location} (which
-itself is a Scheme procedure).
+When you process a file with ly2dvi, a signature line is printed at
+the bottom of the last page. This signature is produced from the
+@code{tagline} field of @code{\header}. The default "Lily was here,
+@var{version number}" is convenient for us programmers. Archived
+the layout of different versions can be compared using archived
+print-outs (that include a version number).
-Editing input files can be quite complicated if you're working with
-large files: if you're digitizing existing music, you have to
-synchronize the .ly file, the sheet music on your lap and the sheet
-music on the screen. The point-and-click mechanism makes it easy to
-find the origin of an error in the LY file: when you view the file with
-Xdvi and click on a note, your editor will jump to the spot where that
-note was entered. For more information, see @ref{Point and click}.
+Many people find the default tagline too droll. If that is the case,
+assign something else to @code{tagline}, as shown above.
@separate
@example
\paper @{
+ linewidth = -1.0 @}
@end example
-The @code{\score} blocks that follow in the file don't have
-@code{\paper} sections, so the settings of this block are substituted: A
-paper block at top level, i.e. not in a @code{\score} block sets the
-default page layout.
+A paper block at top level, i.e. not in a @code{\score} block sets the
+default page layout. The following @code{\score} blocks don't have
+@code{\paper} sections, so the settings of this block are substituted:
+
+The variable @code{linewidth} normally sets the length of the systems
+on the page. However, a negative value has a special meaning. If
+@code{linewidth} is less than 0, no line breaks are inserted into the
+score, and the spacing is set to natural length: a short phrase takes
+up little space, a longer phrase more space.
-@separate
@example
- linewidth = -1.0 @}
-@end example
+%@{
+Mental note: discuss Schenkerian analysis of these key pieces.
+%@}
+@end example
-The variable @code{linewidth} normally sets the length of the systems on
-the page. However, a negative value has a special meaning. If
-@code{linewidth} is less than 0, no line breaks are inserted into the
-score, and the spacing is set to natural length: a short phrase takes up
-little space, a longer phrase more space.
+Mental notes to yourself can be put into comments. There are two types
+of comments. Line comments are introduced by @code{%}, and block
+comments are delimited by @code{%@{} and @code{%@}}.
@separate
@example
-@node A piano excerpt
-@section A piano excerpt
+@example
+\version "1.5.60"
+\header @{
+ title = "Two miniatures"
+ composer = "F. Bar Baz"
+ tagline = "small is beautiful" @}
-Our fourth subject is a piece of 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. It's in the source package
-under the name @file{sammartini.ly}.
+\paper @{ linewidth = -1.0 @}
-@lilypond[verbatim]
-\include "paper16.ly"
+\score @{
+ \notes @{ c'4 d'4 @}
+ \header @{
+ opus = "Opus 1."
+ piece = "Up" @}
+@}
+\score @{
+ \notes @{ d'4 c'4 @}
+ \header @{
+ opus = "Opus 2."
+ piece = "Down" @}
+@}
+@end example
-stemDown = \property Voice.Stem \override #'direction = #-1
-stemUp = \property Voice.Stem \override #'direction = #1
-stemBoth = \property Voice.Stem \revert #'direction
-viola = \notes \relative c' \context Voice = viola {
- <c4-\f-\arpeggio g' c>
- \stemDown g'8. b,16
- s1 s2. r4
- g
-}
+@separate
+@example
+\version "1.6.0"
+@end example
+Lilypond and its language are still under development, and
+occasionally, details of the syntax are changed. This fragment
+indicates for which version the input file was written. When you
+compile this file, the version number will be checked, and you will
+get a warning when the file is too old. This version number is also
+used by the @code{convert-ly} program (See @ref{Older
+LilyPond versions}), which is used to update the file to the latest
+lily version.
-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 Voice.Stem \override #'direction = #-1
- [f,16 g]
- \property Voice.Stem \revert #'direction
- }
- 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 = \repeat unfold 8 \notes
- \transpose c' { \stemUp c8 \stemBoth \stemDown c'8 \stemBoth }
-
-bassvoices = \notes \relative c' {
- c4 g8. b,16
- \autochange Staff \hoomPah
- \translator Staff = down
- \stemDown [c8 c'8] r4
- <g d'> r4
- < {\stemUp r2 <e4 c'> <c8 g'> }
- \context Voice = reallyLow {\stemDown g2 ~ | g4 c8 } >
-}
+@node A piano excerpt
+@section A piano excerpt
-\score {
- \context PianoStaff \notes <
- \context Staff = up < \time 2/2
- \viola
- \oboes
- >
- \context Staff = down < \time 2/2 \clef bass
- \bassvoices
- >
- >
- \midi { }
- \paper {
- indent = 0.0
- linewidth = 15.0 \cm }
-}
-@end lilypond
+Our fourth subject is a piece of 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. It's in the source
+package under the name @file{input/tutorial/sammartini.ly}.
-If this looks like incomprehensible gibberish to you, you are right.
-This example has been doctored to have as many quirks as possible.
+@lilypondfile[smallverbatim]{sammartini.ly}
As you can see, this example features multiple voices on one staff. To
make room for those voices, their notes have to be stemmed in opposite
directions.
-Printed symbols are internally represented by so-called Graphical
-Objects (more colloquially: Grobs). These statements concern the
-grob called `Stem'. Each grob is described by a bunch of settings. These
-setting determine the fonts, offsets, sub-routines to be called on the
-grob, etc. The initial values of these settings are set in the Scheme
-file @file{scm/grob-description.scm}.
-
-@separate
-@example
- stemDown = \property Voice.Stem \override #'direction = #-1
-@end example
-
-Set a property for all Stem grobs in the current Voice:
-@code{direction} is set to @code{-1}, which encodes down. The setting
-remains in effect until it is reverted.
-
-@separate
-@example
- \property Voice.Stem \revert #'direction
-@end example
-
-Revert the to the previous setting. The effect of precisely one
-@code{\stemDown} or @code{\stemUp} is neutralized.
-
-
LilyPond includes the identifiers @code{\stemUp}, @code{\stemDown} along
with some other commonly used formatting instructions, but to explain how
it works, we wrote our own here. Of course, you should use predefined
@separate
@example
-<c4-\f-\arpeggio g' c>
+<c4-\arpeggio g' c>
@end example
The delimiters @code{<} and @code{>} are shorthands for
@code{\simultaneous @{} and @code{@}}. The expression enclosed in
@code{<} and @code{>} is a chord.
-@cindex dynamics
-@cindex loudness
-@cindex forte
@cindex arpeggio
-@code{\f} places a forte symbol under the chord. The forte applies to
-the whole chord, but the syntax requires that commands like forte and
-arpeggio are attached to a note, so here we attach them to the first
-note.
-
@code{\arpeggio} typesets an arpeggio sign (a wavy vertical line) before
the chord.
@separate
@example
- \stemDown
+ \voiceTwo
@end example
+We want the viola to have stems down, and have all the other
+characteristics of a second voice. This is enforced using the
+@code{\voiceTwo} command: it inserts instructions that makes stem,
+ties, slurs, etc. go down.
+
+
@separate
@example
@code{\context}.
@separate
@example
-\stemUp s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
-@end example
-@code{\stemUp} is a reference to the @code{\property \override} command
-defined above.
+\voiceOne s4 g8. b,16 c8 r <e'8. g> <f16 a>
+@end example
+
+The oboes should have stems up, so they should have stems up, to keep
+them from interfering with the staff-jumping bass figure.
+
@separate
@example
-\grace <e8 g> < d4 f> <c2 e>
+\grace <e8( g> < d4 )f> <c2 e>
@end example
@cindex @code{\grace}
@cindex ornaments
@cindex grace notes
@code{\grace} introduces grace notes. It takes one argument, in this
-case a chord.
+case a chord. A slur is introduced starting from the @code{\grace}
+ending on the following chord.
-@ignore
-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}.
-@end ignore
@separate
@example
\times 2/3
of their notated duration, so in this case the fraction is 2/3.
@separate
@example
-@{ <d8 \< f> <e g> <f a> @}
+@{ <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, a crescendo is started with
-@code{\<}. To be precise, the crescendo start is syntactically attached
-to the preceding note, the @code{d}.
-
-@cindex dynamics
-@cindex crescendo
-@cindex @code{\<}
+three chords.
@separate
@example
voice, which continues with upward stems:
@separate
@example
- @{ \times 2/3 @{ a8 g c @} \! c2 @}
+ @{ \times 2/3 @{ a8 g c @} c2 @}
@end example
-@cindex @code{\!}
-
-The crescendo is ended at the half note by the escaped exclamation
-mark @code{\!}.
-@separate
-@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.
@separate
-@example
-\grace
+@example
+\\
@end example
-@cindex Grace context
-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 we fiddle with a property and make a beam. The argument of
-@code{\grace} is sequential music.
-
-@separate
-@example
- \property Voice.Stem \override #'direction = #-1
- [f,16 g]
- \property Voice.Stem \revert #'direction
-@end example
-
-Normally, grace notes are always stem up, but in this case, the upper
-voice interferes, so we set the stems down here.
+The easiest way to enter multiple voices is demonstrated
+here. Separate the components of the voice (single notes or entire
+sequences) with @code{\\} in a simultaneous music expression. The
+@code{\\} separators split first voice, second voice, third voice, and
+so on.
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
@separate
@example
- f8 e e2
+ f,8 e e2
@} >
@end example
This ends the two-part section.
is the to-be-transposed music. As you can see, in this case, the
transposition has no effect, as central C stays at central C.
-The purpose of this no-op is circumventing relative mode. Relative mode
-can not be used together with transposition, so @code{\relative} will
-leave the contents of @code{\hoomPah} alone. We can use it without
-having to worry about getting the motive in a wrong octave.
+The purpose of this no-op is to protect it from being interpreted as
+relative notes. Relative mode can not be used together with
+transposition, so @code{\relative} will leave the contents of
+@code{\hoomPah} alone. We can use it without having to worry about
+getting the motive in a wrong octave.
+@separate
+@cindex staff switch, manual
+@cindex cross staff voice, manual
+@cindex @code{\translator}
+
+@example
+ \translator Staff = down
+ \stemUp
+ c8
+ \translator Staff = up
+ \stemDown
+ c'8 @}
+@end example
+Voices can switch between staves. Here you see two staff switching
+commands. The first one moves to the lower staff, the second one to
+the lower one. If you set stem directions explicitly (using the
+identifiers @code{\stemUp} and @code{\stemDown}.
+
@separate
@example
bassvoices = \notes \relative c' @{
c4 g8. b,16
-\autochange Staff \hoomPah
+\autochange Staff \hoomPah \context Voice
@end example
-@cindex staff switch, automatic
-@cindex cross staff voice, automatic
-@cindex @code{\autochange}
-Voices can switch between staves. The easiest way to get this, is to use
-@code{\autochange}. This command looks at the pitch of each note, and if
-necessary, will cross to the other staff. For this to work, the two
-staves must be called @code{"up"} and @code{"down"}.
@separate
@example
\translator Staff = down
@end ignore
+@node Fine tuning a piece
+@section Fine tuning a piece
+
+In this section, we show some ways to fine tune the final output of a
+piece. We do so using a single measure of a moderately complex piano
+piece: a Brahms intermezzo (opus 119, no. 1). Both fragments (the
+tuned and the untuned are in the @file{input/tutorial/}).
+
+The code for the untuned example shows us some new things.
+
+@lilypondfile[verbatim]{brahms-original.ly}
+
+
+@cindex dynamics
+@cindex loudness
+@cindex forte
+@cindex crescendo
+@cindex @code{\<}
+@cindex @code{\!}
+
+The crescendo is ended at the half note by the escaped exclamation
+mark @code{\!}.
+
+Hairpin dynamics can be indicated using @code{\>} to start a
+decrescendo, and @code{\!} to end one. The crescendo is started using
+@code{\<} and also ended using @code{\!}. Absolute dynamics can be
+entered using @code{\p}, @code{\mf}, etc. All these commands apply to
+the complete chord where they are entered, but for syntactical
+reasons, they must be attached to one of the notes of the chord.
+
+@cindex fingering instructions
+
+Fingering indications are entered simply using @code{-@var{N}}, where
+@var{N} is a digit.
+
+Now that we have the basic piece of music entered, we want to fine
+tune it, so we get something that resembles the original printed
+edition by Schott/Universal Edition:
+
+@lilypondfile{brahms-tweaked.ly}
+
+@cindex tuning grob behavior
+
+The basic process that we follow is that we override defaults in the
+printing system. We do this by setting variables in so-called grobs.
+Printed symbols are internally represented by Graphical Objects
+(Grobs). Each grob is described by a bunch of settings. Every
+setting is a variable: it has a name, and you can assign a value to
+the variable. These setting determine the fonts, offsets, sub-routines
+to be called on the grob, etc. The initial values of these settings
+are set in the Scheme file @file{scm/grob-description.scm}.
+
+@cindex slur attachments
+
+We start with the slur: the slur in the upper part, running from the F
+sharp to the A, runs from stem to stem in the printed edition, while
+ours starts from the note head at the left. The following property
+setting forces all slurs to run from stem to stem (and not from or to
+note head)
+
+@example
+ \property Voice.Slur \set #'attachment = #'(stem . stem)
+@end example
+
+More precisely, this command extends the definition of the @code{Slur}
+object in the current @code{Voice}. The variable @code{attachment} is
+set to the pair of symbols @code{'(stem . stem)}.
+
+Although this is useful information, it is not very helpful: the
+lilypond backend supports approximately 240 variables like
+@code{attachment}, each with their own meaning and own type
+(eg. number, symbol, list, etc). Besides slur, LilyPond has 80
+different types of Grobs, that may be created in 14 different context
+types besides Voice.
+
+@cindex internal documentation
+@cindex finding grobs
+@cindex grob descriptiosn
+
+The interesting information is how you can figure out which properties
+to tune for your own scores. To discover this, you must have a copy of
+the internals document. This is a set of HTML pages, which should be
+included if you run a binary distribution@footnote{You can also
+compile them by executing @code{make -C Documentation/user/
+out/lilypond-internals.html} in the source package.}. This document is
+also available on the web: go to the lilypond website, click
+``Documentation: other'' on the side bar, click
+``lilypond-internals'', under information for users.
+
+You might want to bookmark either the HTML files on disk, or the one
+on the web. One word of caution is in place here: the internals
+documentation is generated from the definitions that lily uses. For
+that reason, it is strongly tied to the version of LilyPond that you
+use. Before you proceed, please make sure that you are using the
+documentation that corresponds to the LilyPond version that you use.
+
+Suppose that you wanted to tune the behavior of the slur. The first
+step is to get some general information on slurs in lilypond. Turn to
+the index, and look up ``slur''. The section on slurs says
+@quotation
+The grob for this object is @internalsref{Slur}, generally in
+@internalsref{Voice} context.
+@end quotation
+
+So the grob for this object is called @code{Slur}, and slurs are
+created in the @code{Voice} context. If you are reading this tutorial
+in the HTML version, then you can simply click Slur, otherwise, you
+must look it up the internal documentation: click ``grob overview'' ,
+and select ``slur'' (the list is alphabetical.)
+
+Now you get a list of all the properties that the slur object
+supports, along with their default values. Among the properties we
+find the @code{attachment} property with its default setting.
+The property documentation explains that the following setting will
+produce the desired effect:
+@example
+ \property Voice.Slur \set #'attachment = #'(stem . stem)
+@end example
+
+If you ran the previous example, you have unknowingly already used
+this kind of command. The @file{ly/property-init.ly} contains the
+definition of @code{\stemUp}
+@example
+ stemUp = \property Voice.Stem \set #'direction = #1
+@end example
+
+
+We also want to move around the fingering `3'. In the printed edition
+it is not above the stem, but a little lower, slightly left of the
+stem. From the user manual, we find that the associated grob is called
+@code{Fingering}, but how do we know if we should use @code{Voice} or
+@code{Staff}. In many cases, @code{Voice} is a safe bet, but you can
+also deduce this information from the internals documentation: if you
+visit the documentation of @code{Fingering}, you will notice
+@example
+Fingering grobs are created by: Fingering_engraver
+@end example
+
+
+
+Clicking @code{Fingering_engraver} will show you the documentation of
+the module responsible for interpreting the fingering instructions and
+translating them to a @code{Fingering} grob. Such a module is called
+an @emph{engraver}. The documentation of the @code{Fingering_engraver}
+says,
+@example
+Fingering_engraver is part of contexts: Voice and TabVoice
+@end example
+so tuning the settings for Fingering should be done using either
+@example
+ \property Voice.Fingering \set @dots{}
+@end example
+or
+@example
+ \property TabVoice.Fingering \set @dots{}
+@end example
+
+Since the @code{TabVoice} is only used for tab notation, we see that
+the first guess @code{Voice} was indeed correct.
+
+@cindex setting grob properties
+@cindex @code{extra-offset}
+
+For shifting the fingering, we use the grob property
+@code{extra-offset}. The following command manually adds an offset to
+the object. We move it a little to the left, and 1.8 staff space
+downwards.
+@example
+ \property Voice.Fingering \set #'extra-offset = #'(-0.3 . -1.8)
+@end example
+The @code{extra-offset} is a low-level feature: it moves around
+objects in the printout; the formatting engine is completely oblivious
+to these offsets. The unit of these offsets are staff-spaces.
+
+@cindex reverting grob properties
+@cindex undoing grob properties
+
+We only want to offset a single grob, so after the F-sharp, we must
+undo the setting. The technical term is to revert the grob property.
+@example
+ \property Voice.Fingering \revert #'extra-offset
+@end example
+
+@cindex property types
+@cindex translator properties
+@cindex grob properties
+@cindex music properties
+
+
+There is three different types of variables in LilyPond, something
+which is confusing at first (and for some, it stays like that).
+Variables such as @code{extra-offset} and @code{attachment} are called
+grob properties. They are something different from the translator
+properties, like @code{autoBeaming}. Finally, music expressions are
+internally also stored using properties, so-called music
+properties. You will encounter the latter type if you run Scheme
+functions on music using @code{\apply}.
+
+The second fingering instruction should be moved up a little, to avoid
+a collision with the slur. This could be achieved with
+@code{extra-offset}, but in this case, a simpler mechanism also
+works. We insert an empty text between the 5 and the note. The empty
+text pushes the fingering instruction away:
+@example
+ a^" "^#'(finger "5")
+@end example
+
+Lilypond tries to put fingering instructions closer to the notes as
+text instructions. To insert an empty text (@code{^" "}) between the
+finger and the note, we have disguised the fingering instruction as a
+text: @code{(finger "5")}.
+
+Normally, one would specify dynamics in a single voice, and start and
+end dynamics (such as @b{f} and @b{p}) will be aligned with
+hairpins. In this case, we want the decrescendo to be in a different
+place from the piano sign. We achieve this by putting the dynamic
+markings in different voices. The crescendo should be above the upper
+staff. This can be forced by the precooked command
+@example
+ \dynamicsUp
+@end example
+
+However, if you do that, the decrescendo will be too close to the
+upper voice, and collide with the stems. Looking at the manual for
+dynamics, we notice that ``Vertical positioning of these symbols is
+handled by the @internalsref{DynamicLineSpanner} grob.''. If we turn
+to the documentation of @code{DynamicLineSpanner}, we find that the
+@code{DynamicLineSpanner} supports several so-called
+`interfaces'. This grob not only puts dynamic objects next to the
+staff (@code{side-position-interface}), but it also groups dynamic
+objects (@code{axis-group-interface}), is considered a dynamic sign
+itself (@code{dynamic-interface}) and is a grob: it has the
+@code{grob-interface}, with all the variables that come with it.
+
+For the moment, we are interested in the side positioning:
+@quotation
+ side-position-interface
+
+ Position a victim object (this one) next to other objects (the
+ support). In this case, the direction signifies where to put the
+ victim object relative to the support (left or right, up or down?)
+@end quotation
+Between the grob and its support (in this case: the notes in the voice
+going down), there should be more space. This space is controlled by
+@code{padding}, so we increase it.
+@example
+ \property Voice.DynamicLineSpanner \override #'padding = #5.0
+@end example
+
+This command is almost like the command for setting slur attachments,
+but subtly different in its details. Grob properties can be
+manipulated with two commands: @code{\override} extends the grob
+variables with a setting, and @code{\revert} releases this
+setting. This has a certain theoretical appeal: the operations are
+simple and symmetric. For practical use, it can be cumbersome. Both
+commands act like parentheses: you should carefully balance the use of
+@code{\override} and @code{\revert}. The @code{\set} command is more
+friendly: it first does a @code{\revert} followed by @code{\override}.
+
+Finally, Brahms uses music notation is a slightly unorthodox way. Ties
+usually happen only within one voice. In this piece, the composer
+gladly produces ties that jump voices. We deal with this by faking
+these ties: whenever we need such a tie, we insert a notehead in a
+different voice, and blank the stem. This is done in the following
+snippet of code.
+
+@example
+ \property Voice.Stem \set #'transparent = ##t
+ d'
+ \property Voice.Stem \revert #'transparent
+@end example
+
+Finally, the last tie is forced up using @code{\tieUp}.
+
+
@node An orchestral score
@section An orchestral score
@code{\score} blocks to produce different combinations of the score.
This orchestral score example consists of three input files. In the
-first file, @file{os-music.ly}, we define the music for all instruments.
-This file will be used both for producing the score and the separate
-parts.
+first file, @file{os-music.ly}, we define the music for all
+instruments. This file will be used both for producing the score and
+the separate parts. Other files reference this file by doing
+@code{\include "os-music.ly"}.
If you were to run LilyPond on this file, no printable output would be
produced.
@subsection The full score
-The second file, @file{os-score.ly} reads the definitions of the first
-(@file{os-music.ly}), and defines the @code{\score} block for the full
+The second file, @file{input/tutorial/os-score.ly} reads the definitions of the first
+(@file{input/tutorial/os-music.ly}), and defines the @code{\score} block for the full
conductor's score.
@example
#(set! point-and-click line-column-location)
@end example
-In a large orchestral score like this you're bound to make some small
-mistakes, so we enable point and click (See @ref{Point and click})
-editing.
+
+This piece of Scheme code sets the Scheme variable
+@code{point-and-click} to the value @var{line-column-location} (which
+itself is a Scheme procedure).
+
+Editing input files can be complicated if you're working with large
+files: if you're digitizing existing music, you have to synchronize
+the .ly file, the sheet music on your lap and the sheet music on the
+screen. The point-and-click mechanism makes it easy to find the
+origin of an error in the LY file: when you view the file with Xdvi
+and click on a note, your editor will jump to the spot where that note
+was entered. For more information, see @ref{Point and click}.
+
@separate
@example
\property Score.BarNumber \override #'padding = #3
@end example
LilyPond prints bar numbers at the start of each line, but
-unfortunately, they end up a bit too close to the staff in this example.
-A bar number internally is a Grob called @var{BarNumber}. BarNumber
-Grobs can be manipulated through their @var{side-position-interface}. One
-of the properties of a @var{side-position-interface} that can be tweaked
-is the @var{padding}: the amount of extra space that is put between this
-Grob and other Grobs. We set the padding to three staff spaces.
+unfortunately, they end up a bit too close to the staff in this
+example. A bar number internally is a Grob called @var{BarNumber}.
+BarNumber Grobs can be manipulated through their
+@var{side-position-interface}. One of the properties of a
+@var{side-position-interface} that can be tweaked is the
+@var{padding}: the amount of extra space that is put between this Grob
+and other Grobs. We set the padding to three staff spaces.
You can find information on all these kind of properties in LilyPond's
automatically generated documentation in
true.
-@node Other ways to run LilyPond
-@section Other ways to run LilyPond
-
-Until now, you have been using @file{ly2dvi} to invoke LilyPond.
-There are three other routes. Firstly, there is a script called
-@code{lilypond-book}, that allows you to freely mix LilyPond input with
-Texinfo or \LaTeX input. For example, this manual was written using
-@code{lilypond-book}. It is discussed below and in @ref{lilypond-book}.
-
-
-Secondly, you can generate PostScript directly. This is useful if you
-can not or do not want to run @TeX{} on your system. To obtain direct
-PostScript output, invoke LilyPond as follows:
-@cindex PostScript output
-@example
-lilypond -f ps test.ly
-@end example
-You have to set some environment variables to view or print this output.
-More information can be found in @ref{Invoking LilyPond}. Since the
-direct Postscript generation has some problems, it is recommended
-to use @file{ly2dvi}.
-
-
-Thirdly, if you want to do special things with your output, you can run
-invoke LilyPond directly:
-@example
-lilypond test.ly
-@end example
-to produce plain @TeX{} output. Note that La@TeX{} will not work on the
-resulting @file{test.tex}. You must run plain @TeX{} on it.
-
-@cindex @TeX{}
-
-
-
-
-
@node Integrating text and music
@section Integrating text and music
hand, simply by importing a PostScript figure into your wordprocessor.
However, there is a also an automated procedure:
-If you use La@TeX{} or texinfo, you can mix text and LilyPond code. A
-script called @code{lilypond-book} will extract the music fragments, run
-LilyPond on them, and put back the resulting notation. lilypond-book is
-described fully in @ref{lilypond-book}, but here we show a small
-example. Since the example also contains explanatory text, we won't
-comment on the contents.
+If you use HTML, La@TeX{} or texinfo, you can mix text and LilyPond
+code. A script called @code{lilypond-book} will extract the music
+fragments, run LilyPond on them, and put back the resulting notation.
+This utility program is described fully in the chapter @ref{Insert
+music snippets into your texts using lilypond-book}. Here we show a
+small example. Since the example also contains explanatory text, we
+won't comment on the contents.
@example
\documentclass[a4paper]@{article@}
$ cd input/tutorial
$ lilypond-book --outdir=out/ lilbook.tex
lilypond-book (GNU LilyPond) 1.3.146
-Reading `/home/hanwen/usr/src/lilypond-1.3.146/input/tutorial/lilbook.tex'
-Reading
-`/home/hanwen/usr/src/lilypond-1.3.146/input/tutorial/sammartini.ly'
+Reading `input/tutorial/lilbook.tex'
+Reading `input/tutorial/sammartini.ly'
@var{lots of stuff deleted}
Writing `out/lilbook.latex'
$ cd out
@node End of tutorial
@section End of tutorial
-That's all folks. From here, you can either try fiddling with input
-files, or you can read the reference manual. You can find more example
-files in @file{input} and @file{input/test}. You can also look at some
-real music. The website @uref{http://www.mutopiaproject.org} has many
-examples of real music typeset by LilyPond.
-
-
-
-@ignore
-
-[TODO
-
-this should be on mutopia website.
-
-]
-
+This is the end of the tutorial. If you came up till here, and
+have understood everything, then you're now an accomplished lilypond
+hacker. From here, you can try fiddling with input
+files, coming back to the reference manual for information.
+Also don't forget to check out the
+@ifhtml
+@uref{../../templates/out-www/templates.html,templates},
+@uref{../../test/out-www/test.html,example} and
+@uref{../../regression/out-www/regression.html,feature test}
+snippets.
+@end ifhtml
+@ifnothtml
+templates, example and feature test snippets.
+@end ifnothtml
+If you want to see real action lilypond, then head over to
+@uref{http://www.mutopiaproject.org}, which has many examples of
+classical music typeset by LilyPond.
-@c waar deze info? is uiteindelijk wel handig, schat ik.
-[TODO: cut blabla]
-
-If you have a big music project, or just a lot of LilyPond input files,
-all generated output from LilyPond, @TeX{} and metafont will clutter
-your working directory. LilyPond comes with a one-size-fits-all
-pre-cooked makefile that helps you manage producing output. It will
-produce all output in the directory @file{out} , generate and track
-dependencies. Also, it helps in preparing your submission to @ref{Mutopia
-project}.
-
-@file{make/ly.make}
-@example
-mkdir my-project
-cd my-project
-cp /usr/share/lilypond/make/ly.make GNUmakefile
-cp /usr/share/doc/lilypond/examples/input/tutorial/minuet.ly .
-make minuet
-[..]
-Generated out/minuet.ps for target minuet.
-@end example
-
-Type @samp{make help} to see possible targets.
-
-[TODO]
-@file{/usr/share/lilypond/doc/lilypond/examples/input/mutopia-header.ly}
-
-
-
-
-
-[TODO: rewrite completely.]
-
-@menu
-* Songs with additional verses::
-@end menu
-
-@end ignore
projects / lilypond.git / blobdiff