@node Putting it all together
@chapter Putting it all together
-This section explains how to use the rest of the documentation and
-how to solve common problems.
+This chapter discusses general LilyPond concepts and how to
+create @code{\score} blocks.
+
@menu
-* Suggestions for writing LilyPond files::
* Extending the templates::
-* Fixing overlapping notation::
* How LilyPond files work::
-* Troubleshooting (taking it all apart)::
+* Score is a single musical expression::
@end menu
-@node Suggestions for writing LilyPond files
-@section Suggestions for writing LilyPond files
-
-Now you're ready to begin writing larger LilyPond files -- not just the
-little examples in the tutorial, but whole pieces. But how should you
-go about doing it?
-
-The best answer is ``however you want to do it.'' As long as LilyPond
-can understand your files and produces the output that you want, it
-doesn't matter what your files look like. That said, sometimes we
-make mistakes when writing files. If LilyPond can't understand your
-files, or produces output that you don't like, how do you fix the
-problem?
-
-Here are a few suggestions that can help you to avoid or fix
-problems:
-
-@itemize @bullet
-@item Include @code{\version} numbers in every file. Note that all
-templates contain a @code{\version "2.6.0"} string. We
-highly recommend that you always include the @code{\version}, no matter
-how small your file is. Speaking from personal experience, it's
-quite frustrating to try to remember which version of LilyPond you were
-using a few years ago. @code{convert-ly} requires you to declare
-which version of LilyPond you used.
-
-@item Include checks: See @ref{Bar check} and @ref{Octave check}. If you
-include checks every so often, then if you make a mistake, you can pinpoint
-it quicker. How often is ``every so often''? It depends on the complexity
-of the music. For very simple music, perhaps just once or twice. For
-very complex music, every bar.
-
-@item One bar per line. If there is anything complicated, either in the music
-itself or in the output you desire, it's often good to write only one bar
-per line. Saving screen space by cramming eight bars per line just isn't
-worth it if you have to `debug' your files.
-
-@item Comment your files, with either bar numbers (every so often) or
-references to musical themes (``second theme in violins'', ``fourth
-variation''). You may not need it when you're writing the piece for
-the first time, but if you want to go back and change something two
-or three years later, you won't know how your file is structured if you
-didn't comment the file.
-
-@item Ident your braces. A lot of problems are caused by an imbalance
-in the number of @code{@{} and @code{@}}.
-
-@end itemize
-
-
@node Extending the templates
@section Extending the templates
soprano part).
@example
-\version "2.6.0"
+\version "2.7.39"
melody = \relative c' @{
\clef treble
\key c \major
\score@{
<<
- \context Voice = one @{
+ \new Voice = "one" @{
\autoBeamOff
\melody
@}
- \lyricsto "one" \new Lyrics \text
+ \new Lyrics \lyricsto "one" \text
>>
\layout @{ @}
\midi @{ \tempo 4=60 @}
Now we want to add a cello part. Let's look at the ``Notes only'' example:
@example
-\version "2.6.0"
+\version "2.7.39"
melody = \relative c' @{
\clef treble
\key c \major
a4 b c d
@}
-
+
\score @{
\new Staff \melody
\layout @{ @}
@code{\layout} or @code{\midi}.
If we simply cut and paste the @code{melody} section, we would end up with
-two @code{melody} sections. So let's rename them. We'll call the one
-for the soprano @code{sopranoMusic}, and the one for the cello can be
-called @code{celloMusic}. While we're doing this, let's rename @code{text}
+two @code{melody} sections. So let's rename them. We'll call the section
+for the soprano @code{sopranoMusic} and the section for the cello
+@code{celloMusic}. While we're doing this, let's rename @code{text}
to be @code{sopranoLyrics}. Remember to rename both instances of all
these names -- both the initial definition (the
@code{melody = relative c' @{ } part) and the name's use (in the
notes.
@example
-\version "2.6.0"
+\version "2.7.39"
sopranoMusic = \relative c' @{
\clef treble
\key c \major
\score@{
<<
- \context Voice = one @{
+ \new Voice = "one" @{
\autoBeamOff
\sopranoMusic
@}
- \lyricsto "one" \new Lyrics \sopranoLyrics
+ \new Lyrics \lyricsto "one" \sopranoLyrics
>>
\layout @{ @}
\midi @{ \tempo 4=60 @}
@noindent
underneath the soprano stuff. We also need to add @code{<<} and
@code{>>} around the music -- that tells LilyPond that there's
-more than one thing (in this case staff) happening at once. The
+more than one thing (in this case, @code{Staff}) happening at once. The
@code{\score} looks like this now
@example
\score@{
-<<
<<
- \context Voice = one @{
- \autoBeamOff
- \sopranoMusic
- @}
- \lyricsto "one" \new Lyrics \sopranoLyrics
+ <<
+ \new Voice = "one" @{
+ \autoBeamOff
+ \sopranoMusic
+ @}
+ \new Lyrics \lyricsto "one" \sopranoLyrics
+ >>
+ \new Staff \celloMusic
>>
- \new Staff \celloMusic
->>
\layout @{ @}
\midi @{ \tempo 4=60 @}
@}
This looks a bit messy; the indentation is messed up now. That is
easily fixed. Here's the complete soprano and cello template.
-@lilypond[quote,verbatim,raggedright]
-\version "2.6.0"
+@lilypond[quote,verbatim,ragged-right]
+\version "2.7.39"
sopranoMusic = \relative c' {
\clef treble
\key c \major
\score{
<<
- <<
- \context Voice = one {
- \autoBeamOff
- \sopranoMusic
- }
- \lyricsto "one" \new Lyrics \sopranoLyrics
- >>
- \new Staff \celloMusic
+ <<
+ \new Voice = "one" {
+ \autoBeamOff
+ \sopranoMusic
+ }
+ \new Lyrics \lyricsto "one" \sopranoLyrics
+ >>
+ \new Staff \celloMusic
>>
\layout { }
\midi { \tempo 4=60 }
-@node Fixing overlapping notation
-@section Fixing overlapping notation
-
-This may come as a surprise, but LilyPond isn't perfect. Some notation
-elements can overlap. This is unfortunate, but (in most cases) is easily
-solved.
-
-@lilypond[quote,fragment,raggedright,verbatim,relative=2]
-e4^\markup{ \italic ritenuto } g b e
-@end lilypond
-
-@cindex padding
-
-The easiest solution is to increase the distance between the object
-(in this case text, but it could easily be fingerings or dynamics
-instead) and the note. In LilyPond, this is called the
-@code{padding} property. For most objects, it is around 1.0 or
-less (it varies with each object). We want to increase it, so let's
-try 1.5
-
-@lilypond[quote,fragment,raggedright,verbatim,relative=2]
-\once \override TextScript #'padding = #1.5
-e4^\markup{ \italic ritenuto } g b e
-@end lilypond
-
-That looks better, but it isn't quite big enough. After experimenting
-with a few values, we think 2.3 is the best number in this case. However,
-this number is merely the result of experimentation and my personal
-taste in notation. Try the above example with 2.3... but also try higher
-(and lower) numbers. Which do you think looks the best?
-
-@cindex extra-offset
-
-Another solution gives us complete control over placing the object -- we
-can move it horizontally or vertically. This is done with the
-@code{extra-offset} property. It is slightly more complicated and can
-cause other problems. When we move objects with @code{extra-offset},
-the movement is done after LilyPond has placed all other objects. This means
-that the result can overlap with other objects.
-
-@lilypond[quote,fragment,raggedright,verbatim,relative=2]
-\once \override TextScript #'extra-offset = #'( 1.0 . -1.0 )
-e4^\markup{ \italic ritenuto } g b e
-@end lilypond
-
-With @code{extra-offset}, the first number controls the horizontal
-movement (left is negative); the second number controls the vertial
-movement (up is positive). After a bit of experimenting, we decided
-that these values look good
-
-@lilypond[quote,fragment,raggedright,verbatim,relative=2]
-\once \override TextScript #'extra-offset = #'( -1.6 . 1.0 )
-e4^\markup{ \italic ritenuto } g b e
-@end lilypond
-
-@noindent
-Again, these numbers are simply the result of a few experiments and
-looking at the output. You might prefer the text to be slightly higher,
-or to the left, or whatever. Try it and look at the result!
-
-
-@seealso
-
-This manual: @ref{The \override command}, @ref{Common tweaks}.
-
-
@node How LilyPond files work
@section How LilyPond files work
@}
@end example
-@noindent
-but most examples also make use of the @code{\relative c'}
+Most examples also make use of the @code{\relative c'}
(or @code{c''}) command. This is not necessary to merely
compile the examples, but in most cases the output will
look very odd if you omit the @code{\relative c'}.
-@lilypond[quote,fragment,raggedright,verbatim]
+@lilypond[quote,fragment,ragged-right,verbatim]
\relative c'' {
c4 a b c
}
\score @{
\relative c'' @{
c4 a b c
- @}
+ @}
@}
@end example
@example
@{
- \new GrandStaff @{
- insert the whole score of a Wager opera in here
- @}
+ \new GrandStaff <<
+ insert the whole score of a Wagner opera in here
+ >>
@}
@end example
@example
\score @{
@{ c'4 a b c' @}
- \layout @{ @}
- \paper @{ @}
- \midi @{ @}
- \header @{ @}
+ \layout @{ @}
+ \paper @{ @}
+ \midi @{ @}
+ \header @{ @}
@}
@end example
@noindent
-Most people put some of those commands outside the
+Some people put some of those commands outside the
@code{\score} block -- for example, @code{\header} is
-almost always placed above the @code{\score}. That's
-just another shorthand.
+often placed above the @code{\score}. That's just
+another shorthand that LilyPond accepts.
Another great shorthand is the ability to define
variables. All the templates use this
@end example
When LilyPond looks at this file, it takes the value of
-@code{melody} (ie everything to the right of the
-@code{melody = }) and inserts it whenever it sees
+@code{melody} (everything after the equals sign) and
+inserts it whenever it sees
@code{\melody}. There's nothing special about the
-name @code{melody}, @code{global}, @code{pianorighthand},
-or @code{foofoobarbaz}. You can use whatever variable
-names you want.
+names -- it could be @code{melody}, @code{global},
+@code{pianorighthand}, or @code{foofoobarbaz}. You
+can use whatever variable names you want. For
+more details, see
+@ref{Saving typing with identifiers and functions}.
For a complete definition
of the input format, see @ref{File structure}.
-@node Troubleshooting (taking it all apart)
-@section Troubleshooting (taking it all apart)
+@node Score is a single musical expression
+@section Score is a single musical expression
-Sooner or later, you will write a file that LilyPond cannot
-compile. The messages that LilyPond gives may help
-you find the error, but in many cases you need to do some
-investigation to determine the source of the problem.
+In the previous section, @ref{How LilyPond files work},
+we saw the general organization of LilyPond input
+files. But we seemed to skip over the most important
+part: how do we figure out what to write after
+@code{\score}?
-The most powerful tool for this purpose is the
-comment (@code{%} and @code{%@{ ... %@}}). If you don't
-know where a problem is, start commenting out huge portions
-of your input file. After you comment out a section, try
-compiling the file again. If it works, then the problem
-must exist in the portion you just commented. If it doens't
-work, then keep on commenting out material until you have
-something that works.
+We didn't skip over it at all. The big mystery is simply
+that there @emph{is} no mystery. This line explains it
+all:
-In an extreme case, you might end up with only
+@quotation
+@emph{A @code{\score} must begin with a single music expression.}
+@end quotation
+
+@noindent
+You may find it useful to review
+@ref{Music expressions explained}. In that section, we
+saw how to build big music expressions from small
+pieces -- we started from notes, then chords, etc. Now
+we're going to start from a big music expression and
+work our way down.
@example
-\score @{ <<
- % \melody
- % \harmony
- % \bass
->>
- \layout@{@}
+\score @{
+ @{ % this brace begins the overall music expression
+ \new GrandStaff <<
+ insert the whole score of a Wagner opera in here
+ >>
+ @} % this brace ends the overall music expression
+ \layout @{ @}
@}
@end example
-@noindent
-(in other words, an empty file)
+A whole Wagner opera would easily double the length of
+this manual, so let's just do a singer and piano. We
+don't need a @code{GrandStaff} for this ensemble, so we
+shall remove it. We @emph{do} need a singer and a piano,
+though.
-If that happens, don't give up. Uncomment a bit -- say,
-the bass part -- and see if it works. If it doesn't,
-then comment out all of the bass music (but leave
-@code{\bass} in the @code{\score} uncommented.
+@example
+\score @{
+ @{
+ <<
+ \new Staff = "singer" <<
+ >>
+ \new PianoStaff = piano <<
+ >>
+ >>
+ @}
+ \layout @{ @}
+@}
+@end example
+
+Remember that we use @code{<<} and @code{>>} to show
+simultaneous music. And we definitely want to show
+the vocal part and piano part at the same time!
@example
-bass = \relative c' {
-%{
- c4 c c c
- d d d d
-%}
-}
+\score @{
+ @{
+ <<
+ \new Staff = "singer" <<
+ \new Voice = "vocal" @{ @}
+ >>
+ \new Lyrics \lyricsto vocal \new Lyrics @{ @}
+ \new PianoStaff = "piano" <<
+ \new Staff = "upper" @{ @}
+ \new Staff = "lower" @{ @}
+ >>
+ >>
+ @}
+ \layout @{ @}
+@}
+@end example
+
+Now we have a lot more details. We have the singer's
+staff: it contains a @code{Voice} (in LilyPond, this
+term refers to a set of notes, not necessarily vocal
+notes -- for example, a violin generally plays one
+voice) and some lyrics. We also have a piano staff:
+it contains an upper staff (right hand) and a lower
+staff (left hand).
+
+At this stage, we could start filling in notes. Inside
+the curly braces next to @code{\new Voice = vocal},
+we could start writing
+
+@example
+\relative c'' @{
+ a4 b c d
+@}
@end example
-Now start slowly uncommenting more and more of the
-@code{bass} part until you find the problem line.
+But if we did that, the @code{\score} section would
+get pretty long, and it would be harder to understand
+what was happening. So let's use identifiers (or
+variables) instead.
+
+@example
+melody = @{ @}
+text = @{ @}
+upper = @{ @}
+lower = @{ @}
+\score @{
+ @{
+ <<
+ \new Staff = "singer" <<
+ \new Voice = "vocal" @{ \melody @}
+ >>
+ \new Lyrics \lyricsto vocal \new Lyrics @{ \text @}
+ \new PianoStaff = "piano" <<
+ \new Staff = "upper" @{ \upper @}
+ \new Staff = "lower" @{ \lower @}
+ >>
+ >>
+ @}
+ \layout @{ @}
+@}
+@end example
+
+@noindent
+Remember that you can use almost any name you like. The
+limitations on identifier names are detailed in
+@ref{File structure}.
+
+When writing a @code{\score} section, or when reading
+one, just take it slowly and carefully. Start with
+the outer layer, then work on each smaller
+layer. It also really helps to be strict with
+indentation -- make sure that each item on the same
+layer starts on the same horizontal position in your
+text editor!
+