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