@menu
* Input files::
-* Music expressions again::
+* A single music expression::
* Titles and headers::
* Paper and pages::
* Music layout::
@code{\layout}. Such a definition at the toplevel changes the default
settings for the block entered.
+@item
+A direct scheme expression, such as
+@code{#(set-default-paper-size "a7" 'landscape)} or
+@code{#(ly:set-option 'point-and-click #f)}.
+
@item
A @code{\header} block. This sets the global header block. This
is the block containing the definitions for book-wide settings, like
@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
current working directory are available to \include, but a file of the same
name in LilyPond's installation takes precedence. Files are
available to \include from directories in the search path specified as an
-option when invoking @code{lilypond --include=DIR} which adds DIR to the search
-path.
+option when invoking @code{lilypond --include=DIR} which adds DIR to the
+search path.
The @code{\include} statement can use full path information, but with the Unix
convention @code{"/"} rather than the DOS/Windows @code{"\"}. For example,
-@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
\book {
\header {
dedication = "dedicated to me"
- title = \markup \center-align { "Title first line" "Title second line, longer" }
+ title = \markup \center-align { "Title first line" "Title second line,
+longer" }
subtitle = "the subtitle,"
- subsubtitle = #(string-append "subsubtitle LilyPond version " (lilypond-version))
+ subsubtitle = #(string-append "subsubtitle LilyPond version "
+(lilypond-version))
poet = "Poet"
composer = \markup \center-align { "composer" \small "(1847-1973)" }
texttranslator = "Text Translator"
- meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge "r" }
- arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
+ meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
+"r" }
+ arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
+#-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
instrument = \markup \bold \italic "instrument"
piece = "Piece"
}
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
@refbugs
-The @code{breakbefore=##t} header requires that there is a @code{piece} header as well. It may be used as a normal header, or left blank (@code{=""}) as in the example above, but it must be present.
+The @code{breakbefore=##t} header requires that there is a @code{piece}
+header as well. It may be used as a normal header, or left blank
+(@code{=""}) as in the example above, but it must be present.
@}
@end example
-The first command sets the size of all pages. The second command sets the size
+The first command sets the size of all pages. The second command sets the
+size
of the pages that the @code{\paper} block applies to -- if the @code{\paper}
block is at the top of the file, then it will apply to all pages. If the
@code{\paper} block is inside a @code{\book}, then the paper size will only
#(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
LilyPond will do page layout, set margins, and add headers and
footers to each page.
+@cindex @code{annotate-spacing}
+@cindex Spacing, display of properties
+
+To graphically display the dimensions of properties that may
+be altered for page formatting, use
+
+@example
+\paper @{
+ annotate-spacing = ##t
+@}
+@end example
+
+@noindent
+All units dimensions are measured in staff spaces. The pairs
+(@var{a},@var{b}) are intervals, where @var{a} is the lower edge and
+@var{b} the upper edge of the interval.
+
The default layout responds to the following settings in the
@code{\paper} block.
@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 false for pieces that have only two or three
+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
The header and footer are created by the functions @code{make-footer}
and @code{make-header}, defined in @code{\paper}. The default
-implementations are in @file{scm/@/page@/-layout@/.scm}.
+implementations are in @file{ly/@/paper@/-defaults@/.ly} and
+@file{ly/@/titling@/-init@/.ly}.
The page layout itself is done by two functions in the
@code{\paper} block, @code{page-music-height} and
The default page header puts the page number and the @code{instrument}
field from the @code{\header} block on a line.
+The titles (from the @code{\header@{@}} section) are treated as a
+system, so @code{ragged-bottom} and @code{ragged-last-bottom} will
+add space between the titles and the first system of the score.
@node Music layout
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)
@c let's wait for a some comments before writing more.
-The vertical spacing on a page can also be changed for each system individually.
+The vertical spacing on a page can also be changed for each system
+individually.
Some examples are found in the example file
@inputfileref{input/regression/,page-spacing.ly}.
-When setting @code{annotatespacing} in the @code{\paper} block LilyPond
+When setting @code{annotate-spacing} in the @code{\paper} block LilyPond
will graphically indicate the dimensions of properties that may be set
for page spacing,
@lilypond[verbatim]
#(set-default-paper-size "a7" 'landscape)
-\paper { annotatespacing = ##t }
+\paper { annotate-spacing = ##t }
{ c4 }
@end lilypond
@cindex @code{indent}
@cindex @code{line-width}
@cindex @code{ragged-right}
+@cindex @code{ragged-last}
@c Although line-width can be set in \layout, it should be set in paper
@c block, to get page layout right.
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
@cindex vertical spacing
-The option @code{raggedlast} is similar to @code{ragged-right}, but
+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
@c interpolate between both these solutions.
+@example
+\layout @{
+ indent = #0
+ line-width = #150
+ ragged-last = ##t
+@}
+@end example
+
@node Line breaking
@subsection Line breaking
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
@refbugs
-The @code{breakbefore=##t} header requires that there is a @code{piece} header as well. It may be used as a normal header, or left blank (@code{=""}) as in the example above, but it must be present.
+The @code{breakbefore=##t} header requires that there is a @code{piece}
+header as well. It may be used as a normal header, or left blank
+(@code{=""}) as in the example above, but it must be present.
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.
projects / lilypond.git / blobdiff