10.1.2 File structure

A .ly file contains any number of toplevel expressions, where a toplevel expression is one of the following

• An output definition, such as \paper, \midi, and \layout. Such a definition at the toplevel changes the default settings for the block entered.
• A direct scheme expression, such as #(set-default-paper-size "a7" 'landscape) or #(ly:set-option 'point-and-click #f).
• A \header block. This sets the global header block. This is the block containing the definitions for book-wide settings, like composer, title, etc.
• A \score block. This score will be collected with other toplevel scores, and combined as a single \book.

  This behavior can be changed by setting the variable toplevel-score-handler at toplevel. The default handler is defined in the init file scm/lily.scm.

  The \score must begin with a music expression, and may contain only one music expression.

• A \book block logically combines multiple movements (i.e., multiple \score blocks) in one document. If there are a number of \scores, one output file will be created for each \book block, in which all corresponding movements are concatenated. The only reason to explicitly specify \book blocks in a .ly file is if you wish multiple output files from a single input file. One exception is within lilypond-book documents, where you explicitly have to add a \book block if you want more than a single \score or \markup in the same example.

  This behavior can be changed by setting the variable toplevel-book-handler at toplevel. The default handler is defined in the init file scm/lily.scm.

• A compound music expression, such as

       { c'4 d' e'2 }
  

  This will add the piece in a \score and format it in a single book together with all other toplevel \scores and music expressions. In other words, a file containing only the above music expression will be translated into

       \book {
         \score {
           \new Staff {
             \new Voice {
               { c'4 d' e'2 }
             }
           }
         }
       	\layout { }
       	\header { }
       }
  

  This behavior can be changed by setting the variable toplevel-music-handler at toplevel. The default handler is defined in the init file scm/lily.scm.

• A markup text, a verse for example

       \markup {
          2.  The first line verse two.
       }
  

  Markup texts are rendered above, between or below the scores or music expressions, wherever they appear.

• An identifier, such as

       foo = { c4 d e d }
  

  This can be used later on in the file by entering \foo. The name of an identifier should have alphabetic characters only; no numbers, underscores or dashes.

The following example shows three things that may be entered at toplevel

\layout {
  % movements are non-justified by default
  ragged-right = ##t
}

\header {
   title = "Do-re-mi"
}

{ c'4 d' e2 }

At any point in a file, any of the following lexical instructions can be entered:

• \version
• \include
• \sourcefilename
• \sourcefileline