infrastructure. Overriding layout decisions in effect accesses the
program internals, which requires Scheme input. Scheme elements are
introduced in a @code{.ly} file with the hash mark
-@code{#}.@footnote{@ref{Scheme tutorial}, contains a short tutorial
+@code{#}.@footnote{@rlearning{Scheme tutorial}, contains a short tutorial
on entering numbers, lists, strings, and symbols in Scheme.}
@subsection Aligning contexts
New contexts may be aligned above or below exisiting contexts. This
-could be useful in setting up a vocal staff (@ref{Vocal ensembles}) and
+could be useful in setting up a vocal staff (@rlearning{Vocal ensembles}) and
in ossia,
@cindex ossia
--- /dev/null
+@c -*- coding: utf-8; mode: texinfo; -*-
+
+@node Fundamental concepts
+@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)
+
+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.
+ \header @{ @}
+ \layout @{ @}
+ \midi @{ @}
+@}
+@end example
+
+@noindent
+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
+
+@example
+@{
+ c4 a b 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
+
+@example
+\score @{
+ \relative c'' @{
+ c4 a b c
+ @}
+@}
+@end example
+
+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
+ >>
+@}
+@end example
+
+@noindent
+Since everything is inside @code{@{ ... @}}, it counts
+as one music expression.
+
+The @code{\score} can contain other things, such as
+
+@example
+\score @{
+ @{ c'4 a b c' @}
+ \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.
+
+@cindex variables
+@cindex identifiers
+
+Another great shorthand is the ability to define
+variables. All the templates use this
+
+@example
+melody = \relative c' @{
+ c4 a b c
+@}
+
+\score @{
+ @{ \melody @}
+@}
+@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
+@ruser{Saving typing with identifiers and functions}.
+
+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 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.
+
+@example
+\score @{
+ @{ % this brace begins the overall music expression
+ \new GrandStaff <<
+ insert the whole score of a Wagner opera in here
+ >>
+ @} % 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.
+
+@example
+\score @{
+ @{
+ <<
+ \new Staff = "singer" <<
+ >>
+ \new PianoStaff = piano <<
+ >>
+ >>
+ @}
+ \layout @{ @}
+@}
+@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!
+
+@example
+\score @{
+ @{
+ <<
+ \new Staff = "singer" <<
+ \new Voice = "vocal" @{ @}
+ >>
+ \new Lyrics \lyricsto vocal \new Lyrics @{ @}
+ \new PianoStaff = "piano" <<
+ \new Staff = "upper" @{ @}
+ \new Staff = "lower" @{ @}
+ >>
+ >>
+ @}
+ \layout @{ @}
+@}
+@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).
+
+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'' @{
+ a4 b c d
+@}
+@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.
+
+@example
+melody = @{ @}
+text = @{ @}
+upper = @{ @}
+lower = @{ @}
+\score @{
+ @{
+ <<
+ \new Staff = "singer" <<
+ \new Voice = "vocal" @{ \melody @}
+ >>
+ \new Lyrics \lyricsto vocal \new Lyrics @{ \text @}
+ \new PianoStaff = "piano" <<
+ \new Staff = "upper" @{ \upper @}
+ \new Staff = "lower" @{ \lower @}
+ >>
+ >>
+ @}
+ \layout @{ @}
+@}
+@end example
+
+@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!
+
+
+
+
+
* Preface:: Preface.
* Introduction:: What, Why, How.
* Tutorial:: A tutorial introduction.
-* Putting it all together:: More explanation about LilyPond
-* concepts.
+* Fundamental concepts:: Basic concepts required for reading
+the rest of this manual.
+* Putting it all together:: More explanation.
* Working on LilyPond projects:: Discusses real-life usage.
* Tweaking output:: Introduction to modifying output.
Appendices
+* Templates:: Ready-made templates.
+* Scheme tutorial:: Programming inside LilyPond.
* GNU Free Documentation License:: License of this document.
* LilyPond index::
@end menu
@include preface.itely
@include introduction.itely
@include tutorial.itely
+@include fundamental.itely
@include putting.itely
@include working.itely
@include tweaks.itely
+@include templates.itely
+@include scheme-tutorial.itely
@include fdl.itexi
@node LilyPond index
Appendices
* Literature list:: Reference works about music notation.
-* Scheme tutorial:: Programming inside LilyPond.
* Notation manual tables:: Tables and charts.
-* Templates:: Ready-made templates.
* Cheat sheet:: Summary of LilyPond syntax.
* GNU Free Documentation License:: License of this document.
* LilyPond command index::
@include literature.itely
-@include scheme-tutorial.itely
@include notation-appendices.itely
-@include templates.itely
@include cheatsheet.itely
@include fdl.itexi
these files end with @samp{.ly}.
@menu
-* File structure (introduction)::
* File structure::
* A single music expression::
* Multiple scores in a book::
@end menu
-@node File structure (introduction)
-@subsection File structure (introduction)
-
-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.
- \header @{ @}
- \layout @{ @}
- \midi @{ @}
-@}
-@end example
-
-@noindent
-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 @ref{File structure}, for
-a list of all such expressions.
-
-
@node File structure
@subsection File structure
@refbugs
Dynamics are not centered, but workarounds do exist. See the
-@q{piano centered dynamics} template in @ref{Piano templates}.
+@q{piano centered dynamics} template in @rlearning{Piano templates}.
@cindex cross staff stem
@cindex stem, cross staff
Advanced tweaks may be performed by using Scheme. If you are
not familiar with Scheme, you may wish to read our
-@ref{Scheme tutorial}.
+@rlearning{Scheme tutorial}.
@menu
* Music functions::
@menu
* Extending the templates::
-* How LilyPond files work::
-* Score is a single musical expression::
* An orchestral part::
@end menu
-@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
-
-@example
-@{
- c4 a b 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
-
-@example
-\score @{
- \relative c'' @{
- c4 a b c
- @}
-@}
-@end example
-
-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
- >>
-@}
-@end example
-
-@noindent
-Since everything is inside @code{@{ ... @}}, it counts
-as one music expression.
-
-The @code{\score} can contain other things, such as
-
-@example
-\score @{
- @{ c'4 a b c' @}
- \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.
-
-@cindex variables
-@cindex identifiers
-
-Another great shorthand is the ability to define
-variables. All the templates use this
-
-@example
-melody = \relative c' @{
- c4 a b c
-@}
-
-\score @{
- @{ \melody @}
-@}
-@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
-@ruser{Saving typing with identifiers and functions}.
-
-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 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.
-
-@example
-\score @{
- @{ % this brace begins the overall music expression
- \new GrandStaff <<
- insert the whole score of a Wagner opera in here
- >>
- @} % 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.
-
-@example
-\score @{
- @{
- <<
- \new Staff = "singer" <<
- >>
- \new PianoStaff = piano <<
- >>
- >>
- @}
- \layout @{ @}
-@}
-@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!
-
-@example
-\score @{
- @{
- <<
- \new Staff = "singer" <<
- \new Voice = "vocal" @{ @}
- >>
- \new Lyrics \lyricsto vocal \new Lyrics @{ @}
- \new PianoStaff = "piano" <<
- \new Staff = "upper" @{ @}
- \new Staff = "lower" @{ @}
- >>
- >>
- @}
- \layout @{ @}
-@}
-@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).
-
-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'' @{
- a4 b c d
-@}
-@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.
-
-@example
-melody = @{ @}
-text = @{ @}
-upper = @{ @}
-lower = @{ @}
-\score @{
- @{
- <<
- \new Staff = "singer" <<
- \new Voice = "vocal" @{ \melody @}
- >>
- \new Lyrics \lyricsto vocal \new Lyrics @{ \text @}
- \new PianoStaff = "piano" <<
- \new Staff = "upper" @{ \upper @}
- \new Staff = "lower" @{ \lower @}
- >>
- >>
- @}
- \layout @{ @}
-@}
-@end example
-
-@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!
-
-
-
-
@node An orchestral part
@cindex choral score
A complete example of a SATB score setup is in section
-@ref{Vocal ensembles}.
+@rlearning{Vocal ensembles}.
@refcommands
@itemize @bullet
@item @strong{Include @code{\version} numbers in every file}. Note that all
-templates contain a @code{\version "2.11.23"} string. We
+templates contain @code{\version} information. We
highly recommend that you always include the @code{\version}, no matter
how small your file is. Speaking from personal experience, it's
quite frustrating to try to remember which version of LilyPond you were
projects / lilypond.git / commitdiff