-@c -*- coding: latin-1; mode: texinfo; -*-
+@c -*- coding: utf-8; mode: texinfo; -*-
@node Putting it all together
@chapter Putting it all together
* Suggestions for writing LilyPond files::
* Extending the templates::
* Fixing overlapping notation::
+* How LilyPond files work::
+* Score is a single musical expression::
+* Troubleshooting (taking it all apart)::
@end menu
@itemize @bullet
@item Include @code{\version} numbers in every file. Note that all
-templates contain a @code{\version "2.6.0"} string. We
+templates contain a @code{\version "2.7.32"} 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
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
+@item One bar per line of text. 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.
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
-don't comment the file.
+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
+
+If you are entering music from an existing score (ie typesetting a
+piece of existing sheet music),
+
+@itemize @bullet
+
+@item Enter one manuscript (the physical copy) system at a time (but still
+only one bar per line of text), and
+check each system when you finish it. You may use the
+@code{showLastLength} command to speed up processing -- see
+@ref{Skipping corrected music}.
+
+@item Define @code{mBreak = @{ \break @}} and insert @code{\mBreak}
+in the input file whenever the manuscript has a line break. This
+makes it much easier to compare the LilyPond music to the original
+music. When you are finished proofreading your score, you may
+define @code{mBreak = @{ @}} to remove all those line breaks. This
+will allow LilyPond to place line breaks wherever it feels are
+best.
@end itemize
soprano part).
@example
-\version "2.4.0"
+\version "2.7.32"
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.4.0"
+\version "2.7.32"
melody = \relative c' @{
\clef treble
\key c \major
notes.
@example
-\version "2.4.0"
+\version "2.7.32"
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 @}
@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.4.0"
+@lilypond[quote,verbatim,ragged-right]
+\version "2.7.32"
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 }
elements can overlap. This is unfortunate, but (in most cases) is easily
solved.
-@lilypond[quote,fragment,raggedright,verbatim,relative=2]
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
e4^\markup{ \italic ritenuto } g b e
@end lilypond
less (it varies with each object). We want to increase it, so let's
try 1.5
-@lilypond[quote,fragment,raggedright,verbatim,relative=2]
+@lilypond[quote,fragment,ragged-right,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, I think 2.3 is the best number. I leave this as an
-exercise for the reader.
+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
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]
+@lilypond[quote,fragment,ragged-right,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, I decided
+movement (up is positive). After a bit of experimenting, we decided
that these values look good
-@lilypond[quote,fragment,raggedright,verbatim,relative=2]
+@lilypond[quote,fragment,ragged-right,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
+
+The LilyPond input format is quite free-form, giving experienced
+users a lot of flexibility to structure their files however they
+wish. However, this flexibility can make things confusing for
+new users. This section will explain some of this structure, but
+may gloss over some details in favor of simplicity. For a complete
+description of the input format, see @ref{File structure}.
+
+Most examples in this manual are little snippets -- for example
+
+@example
+c4 a b c
+@end example
+
+As you are (hopefully) aware by now, this will not compile by
+itself. These examples are shorthand for complete
+examples. They all need at least curly braces to compile
+
+@example
+@{
+ c4 a b c
+@}
+@end example
+
+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,ragged-right,verbatim]
+\relative c'' {
+ c4 a b c
+}
+@end lilypond
+
+Now we get to the only real stumbling block: LilyPond
+input in this form is actually @emph{another}
+shorthand. Although it compiles and displays the
+correct output, it is shorthand for
+
+@example
+\score @{
+ \relative c'' @{
+ c4 a b c
+ @}
+@}
+@end example
+
+A @code{\score} must begin with a single music
+expression. Remember that a music expression could
+be anything from a single note to a huge
+
+@example
+@{
+ \new GrandStaff <<
+ insert the whole score of a Wagner opera in here
+ >>
+@}
+@end example
+
+@noindent
+Since everything is inside @code{@{ ... @}}, it counts
+as one music expression.
+
+The @code{\score} can contain other things, such as
+
+@example
+\score @{
+ @{ c'4 a b c' @}
+ \layout @{ @}
+ \paper @{ @}
+ \midi @{ @}
+ \header @{ @}
+@}
+@end example
+
+@noindent
+Most 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.
+
+Another great shorthand is the ability to define
+variables. All the templates use this
+
+@example
+melody = \relative c' @{
+ c4 a b c
+@}
+
+\score @{
+ @{ \melody @}
+@}
+@end example
+
+When LilyPond looks at this file, it takes the value of
+@code{melody} (everything after the equals sign) and
+inserts it whenever it sees
+@code{\melody}. There's nothing special about the
+names -- it could be @code{melody}, @code{global},
+@code{pianorighthand}, or @code{foofoobarbaz}. You
+can use whatever variable names you want.
+
+For a complete definition
+of the input format, see @ref{File structure}.
+
+
+@node Score is a single musical expression
+@section Score is a single musical expression
+
+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}?
+
+We didn't skip over it at all. The big mystery is simply
+that there @emph{is} no mystery. This line explains it
+all:
+
+@example
+A @code{\score} must begin with a single music expression.
+@end example
+
+@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 @{
+ @{ % 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
+
+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.
+
+@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
+\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
+
+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!
+
+
+@node Troubleshooting (taking it all apart)
+@section Troubleshooting (taking it all apart)
+
+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.
+
+The most powerful tools for this purpose are the
+single line comment (indicated by @code{%}) and the block
+comment (indicated by @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 doesn't
+work, then keep on commenting out material until you have
+something that works.
+
+In an extreme case, you might end up with only
+
+@example
+\score @{
+ <<
+ % \melody
+ % \harmony
+ % \bass
+ >>
+ \layout@{@}
+@}
+@end example
+
+@noindent
+(in other words, a file without any music)
+
+If that happens, don't give up. Uncomment a bit -- say,
+the bass part -- and see if it works. If it doesn't work,
+then comment out all of the bass music (but leave
+@code{\bass} in the @code{\score} uncommented.
+
+@example
+bass = \relative c' @{
+%@{
+ c4 c c c
+ d d d d
+%@}
+@}
+@end example
+
+Now start slowly uncommenting more and more of the
+@code{bass} part until you find the problem line.
+
projects / lilypond.git / blobdiff