| [ << General input and output ] | [Top][Contents][Index] | [ Spacing issues >> ] |
| [ < Output file names ] | [ Up : Input structure ] | [ Titles and headers > ] |
3.1.5 File structure
A ‘.ly’ file may contain 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 book-wide settings. If more than one such definition of the same type is entered at the top level the definitions are combined, but in conflicting situations the later definitions take precedence. For details of how this affects the\layoutblock see The\layoutblock. -
A direct scheme expression, such as
#(set-default-paper-size "a7" 'landscape)or#(ly:set-option 'point-and-click #f). -
A
\headerblock. This sets the global (i.e., the top of file) header block. This is the block containing the default settings of titling fields like composer, title, etc., for all books within the file (see Titles explained). -
A
\scoreblock. This score will be collected with other toplevel scores, and combined as a single\book. This behavior can be changed by setting the variabletoplevel-score-handlerat toplevel. (The default handler is defined in the file ‘../scm/lily-library.scm’ and set in the file ‘../ly/declarations-init.ly’.) -
A
\bookblock logically combines multiple movements (i.e., multiple\scoreblocks) in one document. If there are a number of\scores, one output file will be created for each\bookblock, in which all corresponding movements are concatenated. The only reason to explicitly specify\bookblocks in a ‘.ly’ file is if you wish to create multiple output files from a single input file. One exception is within lilypond-book documents, where you explicitly have to add a\bookblock if you want more than a single\scoreor\markupin the same example. This behavior can be changed by setting the variabletoplevel-book-handlerat toplevel. The default handler is defined in the init file ‘../scm/lily.scm’. -
A
\bookpartblock. A book may be divided into several parts, using\bookpartblocks, in order to ease the page breaking, or to use different\papersettings in different parts. -
A compound music expression, such as
{ c'4 d' e'2 }This will add the piece in a
\scoreand 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 { } } \paper { } \header { } }This behavior can be changed by setting the variable
toplevel-music-handlerat 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.
-
A variable, such as
foo = { c4 d e d }This can be used later on in the file by entering
\foo. The name of a variable should not contain (ASCII) numbers, multiple underscores, multiple dashes or space characters. All other characters Unicode provides are allowed, for example Latin, Greek, Chinese or Cyrillic. Non-adjacent single underscores and dashes are allowed, too. In other words, variable names likeHornIIIorαβγXIIwork.Any combination of characters is allowed if the variable name is enclosed in double quotation marks. In this case backslashes and double quotation marks need to be escaped with backslashes (not that you actually should use them). Examples:
"foo bar","a-b-c","Horn 3".
The following example shows three things that may be entered at toplevel
\layout {
% Don't justify the output
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 -
A single-line comment, introduced by a leading
%sign. -
A multi-line comment delimited by
%{ … %}.
Whitespace between items in the input stream is generally ignored, and may be freely omitted or extended to enhance readability. However, whitespace should always be used in the following circumstances to avoid errors:
- Around every opening and closing curly bracket.
- After every command or variable, i.e., every item that
begins with a
\sign. - After every item that is to be interpreted as a Scheme
expression, i.e., every item that begins with a
#sign. - To separate all elements of a Scheme expression.
- In
lyricmodebefore and after\setand\overridecommands.
See also
Learning Manual: How LilyPond input files work.
Notation Reference:
Titles explained,
The \layout block.
| [ << General input and output ] | [Top][Contents][Index] | [ Spacing issues >> ] |
| [ < Output file names ] | [ Up : Input structure ] | [ Titles and headers > ] |