X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fputting.itely;h=0cc5ecd908ff926d5c6b9226482325ee3f4d314f;hb=af770f3440264c18ce01525dce1aa76b86ace0d5;hp=28f3e4a8aef579150d278a4aa9bc5a08c1cb4066;hpb=eae1ceba11cf0b64e32caf00b1303f27c3e43bab;p=lilypond.git diff --git a/Documentation/user/putting.itely b/Documentation/user/putting.itely index 28f3e4a8ae..0cc5ecd908 100644 --- a/Documentation/user/putting.itely +++ b/Documentation/user/putting.itely @@ -1,61 +1,449 @@ -@c -*- coding: latin-1; mode: texinfo; -*- +@c -*- coding: utf-8; mode: texinfo; -*- @node Putting it all together @chapter Putting it all together -This section will demonstrate more complicated stuff in LilyPond, probably -via annotated examples. It's currently incomplete and serves as a -placeholder so that the chapter numbering doesn't change later. +This chapter discusses general LilyPond concepts and how to +create @code{\score} blocks. + @menu -* Suggestions for writing LilyPond files:: +* Extending the templates:: +* How LilyPond files work:: +* Score is a single musical expression:: @end menu -@c explain \score{} ? Add a note to the tutorial? - -@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.4.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 -don't comment the file. - -@end itemize + +@node Extending the templates +@section Extending the templates + +You've read the tutorial, you know how to write music. But how can you +get the staves that you want? The templates are ok, but what if you +want something that isn't covered? + +Start off with the template that seems closest to what you want to end +up with. Let's say that you want to write something for soprano and +cello. In this case, we would start with ``Notes and lyrics'' (for the +soprano part). + +@example +\version "2.9.13" +melody = \relative c' @{ + \clef treble + \key c \major + \time 4/4 + + a4 b c d +@} + +text = \lyricmode @{ + Aaa Bee Cee Dee +@} + +\score@{ + << + \new Voice = "one" @{ + \autoBeamOff + \melody + @} + \new Lyrics \lyricsto "one" \text + >> + \layout @{ @} + \midi @{ @} +@} +@end example + +Now we want to add a cello part. Let's look at the ``Notes only'' example: + +@example +\version "2.9.13" +melody = \relative c' @{ + \clef treble + \key c \major + \time 4/4 + + a4 b c d +@} + +\score @{ +\new Staff \melody +\layout @{ @} +\midi @{ @} +@} +@end example + +We don't need two @code{\version} commands. We'll need the @code{melody} +section. We don't want two @code{\score} sections -- if we had two +@code{\score}s, we'd get the two parts separately. We want them together, +as a duet. Within the @code{\score} section, we don't need two +@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 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 +@code{\score} section). + +While we're doing this, let's change the cello part's staff -- celli +normally use bass clef. We'll also give the cello some different +notes. + +@example +\version "2.9.13" +sopranoMusic = \relative c' @{ + \clef treble + \key c \major + \time 4/4 + + a4 b c d +@} + +sopranoLyrics = \lyricmode @{ + Aaa Bee Cee Dee +@} + +celloMusic = \relative c @{ + \clef bass + \key c \major + \time 4/4 + + d4 g fis8 e d4 +@} + +\score@{ + << + \new Voice = "one" @{ + \autoBeamOff + \sopranoMusic + @} + \new Lyrics \lyricsto "one" \sopranoLyrics + >> + \layout @{ @} + \midi @{ @} +@} +@end example + +This is looking promising, but the cello part won't appear in the +score -- we haven't used it in the @code{\score} section. If we +want the cello part to appear under the soprano part, we need to add + +@example +\new Staff \celloMusic +@end example + +@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, @code{Staff}) happening at once. The +@code{\score} looks like this now + +@example +\score@{ + << + << + \new Voice = "one" @{ + \autoBeamOff + \sopranoMusic + @} + \new Lyrics \lyricsto "one" \sopranoLyrics + >> + \new Staff \celloMusic + >> + \layout @{ @} + \midi @{ @} +@} +@end example + +@noindent +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,ragged-right] +\version "2.9.13" +sopranoMusic = \relative c' { + \clef treble + \key c \major + \time 4/4 + + a4 b c d +} + +sopranoLyrics = \lyricmode { + Aaa Bee Cee Dee +} + +celloMusic = \relative c { + \clef bass + \key c \major + \time 4/4 + + d4 g fis8 e d4 +} + +\score{ + << + << + \new Voice = "one" { + \autoBeamOff + \sopranoMusic + } + \new Lyrics \lyricsto "one" \sopranoLyrics + >> + \new Staff \celloMusic + >> + \layout { } + \midi { } +} +@end lilypond + + + +@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 @{ @} + \midi @{ @} + \header @{ @} +@} +@end example + +@noindent +Some people put some of those commands outside the +@code{\score} block -- for example, @code{\header} is +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 + +@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 +more details, see +@ref{Saving typing with identifiers and functions}. + +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: + +@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 @{ + @{ % 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!