@chapter Fundamental concepts
@menu
-* File structure (introduction)::
* How LilyPond files work::
* Score is a single musical expression::
@end menu
-@node File structure (introduction)
-@section File structure (introduction)
+@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 @ruser{File structure}.
A basic example of a lilypond input file is
@example
\version "2.11.23"
\score @{
- @{ @} % this is a single music expression;
- % all the music goes in here.
+ @{@var{...music expression...}@} % all the music goes here!
\header @{ @}
\layout @{ @}
\midi @{ @}
There are many variations of this basic pattern, but this
example serves as a useful starting place.
-The major part of this manual is concerned with entering various
-forms of music in LilyPond. However, many music expressions are not
-valid input on their own, for example, a @code{.ly} file containing
-only a note
-@example
-c'4
-@end example
-
-@noindent
-will result in a parsing error. Instead, music should be inside other
-expressions, which may be put in a file by themselves. Such
-expressions are called toplevel expressions; see @ruser{File structure}, for
-a list of all such expressions.
-
-
-@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 @ruser{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
+At this point, you may be confused, since you have never seen a
+@code{\score@{@}} before. This is because LilyPond automatically
+adds the extra commands when you give it simple input. LilyPond
+treats input like this:
@example
-@{
- c4 a b c
+\relative c'' @{
+ c4 a d 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
+@noindent
+as shorthand for this:
@example
\score @{
\relative c'' @{
c4 a b c
@}
+ \layout @{ @}
@}
@end example
+In other words, if the input contains a single music expression,
+LilyPond will interpret the file as though the music expression
+was wrapped up inside a @code{\score@{@}}.
+
+@smallspace
+
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
+ @var{...insert the whole score of a Wagner opera in here...}
>>
@}
@end example
Since everything is inside @code{@{ ... @}}, it counts
as one music expression.
-The @code{\score} can contain other things, such as
+As we saw previously, the @code{\score} can contain other things,
+such as
@example
\score @{
@{ c'4 a b c' @}
+ \header @{ @}
\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.
+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.
+
+@smallspace
@cindex variables
@cindex identifiers
-Another great shorthand is the ability to define
-variables. All the templates use this
+Another great shorthand is the ability to define identifiers. All
+the templates use this
@example
melody = \relative c' @{
@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
+@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
@ruser{Saving typing with identifiers and functions}.
-For a complete definition
-of the input format, see @ruser{File structure}.
+
+@seealso
+
+For a complete definition of the input format, see @ruser{File
+structure}.
@node Score is a single musical expression
@section Score is a single musical expression
-In the previous section, @ruser{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 saw the general organization of LilyPond input files in the
+previous section, @ref{How LilyPond files work}. 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:
+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
-@ruser{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.
+You may find it useful to review @ruser{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
+ @{ % this brace begins the overall music expression
\new GrandStaff <<
- insert the whole score of a Wagner opera in here
+ @var{...insert the whole score of a Wagner opera in here...}
>>
- @} % this brace ends the overall music expression
+ @} % 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.
+A whole Wagner opera would easily double the length of this
+manual, so let's just add 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 @{
@}
@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!
+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, not one after the other!
@example
\score @{
@}
@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).
+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
+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'' @{
@}
@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.
+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 = @{ @}
@noindent
Remember that you can use almost any name you like. The
-limitations on identifier names are detailed in
-@ruser{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!
-
+limitations on identifier names are detailed in @ruser{File
+structure}.
+
+When writing (or reading) a @code{\score} section, 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.
projects / lilypond.git / commitdiff