@menu
* Input files::
-* Music expressions again::
+* A single music expression::
* Titles and headers::
* Paper and pages::
* Music layout::
@code{toplevel-score-handler} at toplevel. The default handler is
defined in the init file @file{scm/@/lily@/.scm}.
-The @code{\score} must begin with music, and may contain only
-one music block.
+The @code{\score} must begin with a music expression, and may
+contain only one music expression.
@item
A @code{\book} block logically combines multiple movements
-(i.e., multiple @code{\score} blocks) in one document. A number of
-@code{\scores} creates a single output file, where all movement are
-concatenated.
+(i.e., multiple @code{\score} blocks) in one document. If there are
+a number of @code{\scores}, a single output file will be created
+in which all movements are concatenated.
This behavior can be changed by setting the variable
@code{toplevel-book-handler} at toplevel. The default handler is
-@c FIXME: --must-- delete/modify this before 2.8.0!!! -gp
-@node Music expressions again
-@section Music expressions again
+@node A single music expression
+@section A single music expression
-Should we include anything about this here?
+A @code{\score} must contain a single music expression. However,
+this music expression may be of any size. Recall that music
+expressions may be included inside other expressions to form
+larger expressions. All of these examples are single music
+expressions; note the curly braces @{ @} or angle brackets <<
+>> at the beginning and ending of the music.
+
+@example
+@{ c'4 c' c' c' @}
+@end example
+
+@lilypond[ragged-right,verbatim,quote]
+{
+ { c'4 c' c' c'}
+ { d'4 d' d' d'}
+}
+@end lilypond
+
+@lilypond[ragged-right,verbatim,quote]
+<<
+ \new Staff { c'4 c' c' c' }
+ \new Staff { d'4 d' d' d' }
+>>
+@end lilypond
+
+@example
+@{
+ \new GrandStaff <<
+ \new StaffGroup <<
+ \new Staff @{ \flute @}
+ \new Staff @{ \oboe @}
+ >>
+ \new StaffGroup <<
+ \new Staff @{ \violinI @}
+ \new Staff @{ \violinII @}
+ >>
+ >>
+@}
+@end example
@node Titles and headers
composer = "Composer"
@}
\header @{
- title = "Title"
+ piece = "Piece"
@}
\score @{
\new Staff @{ c'4 @}
\header @{
- title = "New title" % overwrite previous one
+ piece = "New piece" % overwrite previous one
@}
@}
@end example
#(set-default-paper-size "a6" 'landscape)
@end example
+Setting the paper size will adjust a number of @code{\paper} variables
+(such as margins). To use a particular paper size with altered
+@code{\paper} variables, set the paper size before setting the variables.
+
@node Page formatting
@subsection Page formatting
@cindex @code{ragged-bottom}
@item ragged-bottom
-If set to true, systems will not be spread across the page.
+If set to true, systems will not be spread vertically across the page. This
+does not affect the last page.
This should be set to true for pieces that have only two or three
systems per page, for example orchestral scores.
@cindex @code{ragged-last-bottom}
@item ragged-last-bottom
-If set to false, systems will be spread to fill the last page.
+If set to false, systems will be spread vertically to fill the last page.
Pieces that amply fill two pages or more should have this set to
true.
default, for example
@lilypond[ragged-right]
-\paper {
- systemSeparatorMarkup = \slashSeparator
+\book {
+ \score {
+ \relative { c1 \break c1 }
+ }
+ \paper {
+ systemSeparatorMarkup = \slashSeparator
+ }
}
-
-\relative { c1 \break c1 }
@end lilypond
Normally staves are stacked vertically. To make staves maintain a
distance, their vertical size is padded. This is done with the
-property @code{minimum-Y-extent}. It takes a pair of numbers, so
-if you want to make it smaller than its default @code{#'(-4 . 4)},
-then you could set. When applied to a
+property @code{minimum-Y-extent}. When applied to a
@internalsref{VerticalAxisGroup}, it controls the size of a horizontal
-line, such as a staff or a line of lyrics.
+line, such as a staff or a line of lyrics. @code{minimum-Y-extent}
+takes a pair of numbers, so
+if you want to make it smaller than its default @code{#'(-4 . 4)}
+then you could set
@example
\override Staff.VerticalAxisGroup #'minimum-Y-extent = #'(-3 . 3)
the lines.
If @code{ragged-right} is set to true in the @code{\layout} block, then
-the lines are justified at their natural length. This is useful for
+systems ends at their natural horizontal length, instead of being spread
+horizontally to fill the whole line. This is useful for
short fragments, and for checking how tight the natural spacing is.
@cindex page layout
The option @code{ragged-last} is similar to @code{ragged-right}, but
only affects the last line of the piece. No restrictions are put on
that line. The result is similar to formatting text paragraphs. In a
-paragraph, the last line simply takes its natural length.
+paragraph, the last line simply takes its natural horizontal length.
@c Note that for text there are several options for the last line.
@c While Knuth TeX uses natural length, lead typesetters use the same
@c stretch as the previous line. eTeX uses \lastlinefit to
complicated; see @inputfileref{input/regression/,page-layout-twopass.ly}
for details.
+@refbugs
+
+Line breaks can only occur if there is a ``proper'' bar line. A note
+which is hanging over a bar line is not proper, such as
+
+@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
+c4 c2 c2 \break % this does nothing
+c2 c4 | % a break here would work
+c4 c2 c4 ~ \break % as does this break
+c4 c2 c4
+@end lilypond
+
@node Page breaking
@subsection Page breaking
For each type of MIDI instrument, a volume range can be defined. This
gives a basic equalizer control, which can enhance the quality of
the MIDI output remarkably. The equalizer can be controlled by
-setting @code{instrumentEqualizer}.
+setting @code{instrumentEqualizer}, or by setting
+
+@example
+\set Staff.midiMinimumVolume = #0.2
+\set Staff.midiMaximumVolume = #0.8
+@end example
To remove dynamics from the MIDI output, insert the following lines
in the @code{\midi@{@}} section.