Documentation/user/fundamental.itely

   1 @c -*- coding: utf-8; mode: texinfo; -*-
   2 @c This file is part of lilypond-learning.tely
   3
   4 @node Fundamental concepts
   5 @chapter Fundamental concepts
   6
   7 @menu
   8 * How LilyPond files work::
   9 * Score is a single musical expression::
  10 @end menu
  11
  12
  13 @node How LilyPond files work
  14 @section How LilyPond files work
  15
  16 The LilyPond input format is quite free-form, giving experienced
  17 users a lot of flexibility to structure their files however they
  18 wish.  However, this flexibility can make things confusing for new
  19 users.  This section will explain some of this structure, but may
  20 gloss over some details in favor of simplicity.  For a complete
  21 description of the input format, see @ruser{File structure}.
  22
  23 A basic example of a lilypond input file is
  24
  25 @example
  26 \version "2.11.23"
  27 \score @{
  28   @{@var{...music expression...}@}  % all the music goes here!
  29   \header @{ @}
  30   \layout @{ @}
  31   \midi @{ @}
  32 @}
  33 @end example
  34
  35 @noindent
  36 There are many variations of this basic pattern, but this
  37 example serves as a useful starting place.
  38
  39 At this point, you may be confused, since you have never seen a
  40 @code{\score@{@}} before.  This is because LilyPond automatically
  41 adds the extra commands when you give it simple input.  LilyPond
  42 treats input like this:
  43
  44 @example
  45 \relative c'' @{
  46   c4 a d c
  47 @}
  48 @end example
  49
  50 @noindent
  51 as shorthand for this:
  52
  53 @example
  54 \score @{
  55   \relative c'' @{
  56     c4 a b c
  57   @}
  58   \layout @{ @}
  59 @}
  60 @end example
  61
  62 In other words, if the input contains a single music expression,
  63 LilyPond will interpret the file as though the music expression
  64 was wrapped up inside a @code{\score@{@}}.
  65
  66 @smallspace
  67
  68 A @code{\score} must begin with a single music
  69 expression.  Remember that a music expression could
  70 be anything from a single note to a huge
  71
  72 @example
  73 @{
  74   \new GrandStaff <<
  75     @var{...insert the whole score of a Wagner opera in here...}
  76   >>
  77 @}
  78 @end example
  79
  80 @noindent
  81 Since everything is inside @code{@{ ... @}}, it counts
  82 as one music expression.
  83
  84 As we saw previously, the @code{\score} can contain other things,
  85 such as
  86
  87 @example
  88 \score @{
  89   @{ c'4 a b c' @}
  90   \header @{ @}
  91   \layout @{ @}
  92   \midi @{ @}
  93 @}
  94 @end example
  95
  96 @noindent
  97 Some people put some of those commands outside the @code{\score}
  98 block -- for example, @code{\header} is often placed above the
  99 @code{\score}.  That's just another shorthand that LilyPond
 100 accepts.
 101
 102 @smallspace
 103
 104 @cindex variables
 105 @cindex identifiers
 106
 107 Another great shorthand is the ability to define identifiers.  All
 108 the templates use this
 109
 110 @example
 111 melody = \relative c' @{
 112   c4 a b c
 113 @}
 114
 115 \score @{
 116   @{ \melody @}
 117 @}
 118 @end example
 119
 120 When LilyPond looks at this file, it takes the value of
 121 @code{melody} (everything after the equals sign) and inserts it
 122 whenever it sees @code{\melody}.  There's nothing special about
 123 the names -- it could be @code{melody}, @code{global},
 124 @code{pianorighthand}, or @code{foofoobarbaz}.  You can use
 125 whatever variable names you want.  For more details, see
 126 @ruser{Saving typing with identifiers and functions}.
 127
 128
 129 @seealso
 130
 131 For a complete definition of the input format, see @ruser{File
 132 structure}.
 133
 134
 135 @node Score is a single musical expression
 136 @section Score is a single musical expression
 137
 138 We saw the general organization of LilyPond input files in the
 139 previous section, @ref{How LilyPond files work}.  But we seemed to
 140 skip over the most important part: how do we figure out what to
 141 write after @code{\score}?
 142
 143 We didn't skip over it at all.  The big mystery is simply that
 144 there @emph{is} no mystery.  This line explains it all:
 145
 146 @quotation
 147 @emph{A @code{\score} must begin with a single music expression.}
 148 @end quotation
 149
 150 @noindent
 151 You may find it useful to review @ruser{Music expressions
 152 explained}.  In that section, we saw how to build big music
 153 expressions from small pieces -- we started from notes, then
 154 chords, etc.  Now we're going to start from a big music expression
 155 and work our way down.
 156
 157 @example
 158 \score @{
 159   @{ % this brace begins the overall music expression
 160     \new GrandStaff <<
 161       @var{...insert the whole score of a Wagner opera in here...}
 162     >>
 163   @} % this brace ends the overall music expression
 164   \layout @{ @}
 165 @}
 166 @end example
 167
 168 A whole Wagner opera would easily double the length of this
 169 manual, so let's just add a singer and piano.  We don't need a
 170 @code{GrandStaff} for this ensemble, so we shall remove it.  We
 171 @emph{do} need a singer and a piano, though.
 172
 173 @example
 174 \score @{
 175   @{
 176     <<
 177       \new Staff = "singer" <<
 178       >>
 179       \new PianoStaff = piano <<
 180       >>
 181     >>
 182   @}
 183   \layout @{ @}
 184 @}
 185 @end example
 186
 187 Remember that we use @code{<<} and @code{>>} to show simultaneous
 188 music.  And we definitely want to show the vocal part and piano
 189 part at the same time, not one after the other!
 190
 191 @example
 192 \score @{
 193   @{
 194     <<
 195       \new Staff = "singer" <<
 196         \new Voice = "vocal" @{ @}
 197       >>
 198       \new Lyrics \lyricsto vocal \new Lyrics @{ @}
 199       \new PianoStaff = "piano" <<
 200         \new Staff = "upper" @{ @}
 201         \new Staff = "lower" @{ @}
 202       >>
 203     >>
 204   @}
 205   \layout @{ @}
 206 @}
 207 @end example
 208
 209 Now we have a lot more details.  We have the singer's staff: it
 210 contains a @code{Voice} (in LilyPond, this term refers to a set of
 211 notes, not necessarily vocal notes -- for example, a violin
 212 generally plays one voice) and some lyrics.  We also have a piano
 213 staff: it contains an upper staff (right hand) and a lower staff
 214 (left hand).
 215
 216 At this stage, we could start filling in notes.  Inside the curly
 217 braces next to @code{\new Voice = vocal}, we could start writing
 218
 219 @example
 220 \relative c'' @{
 221   a4 b c d
 222 @}
 223 @end example
 224
 225 But if we did that, the @code{\score} section would get pretty
 226 long, and it would be harder to understand what was happening.  So
 227 let's use identifiers (or variables) instead.
 228
 229 @example
 230 melody = @{ @}
 231 text = @{ @}
 232 upper = @{ @}
 233 lower = @{ @}
 234 \score @{
 235   @{
 236     <<
 237       \new Staff = "singer" <<
 238         \new Voice = "vocal" @{ \melody @}
 239       >>
 240       \new Lyrics \lyricsto vocal \new Lyrics @{ \text @}
 241       \new PianoStaff = "piano" <<
 242         \new Staff = "upper" @{ \upper @}
 243         \new Staff = "lower" @{ \lower @}
 244       >>
 245     >>
 246   @}
 247   \layout @{ @}
 248 @}
 249 @end example
 250
 251 @noindent
 252 Remember that you can use almost any name you like.  The
 253 limitations on identifier names are detailed in @ruser{File
 254 structure}.
 255
 256 When writing (or reading) a @code{\score} section, just take it
 257 slowly and carefully.  Start with the outer layer, then work on
 258 each smaller layer.  It also really helps to be strict with
 259 indentation -- make sure that each item on the same layer starts
 260 on the same horizontal position in your text editor.
 261
 262
 263
 264